[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docmentation/FAQs

On 9/22/06, David Tangye <..hidden..> wrote:

On Fri, 2006-09-22 at 07:54 -0700, Joshua D. Drake wrote:

> Your reasons can be solved by other mechanisms as well. Latex is just
> the one that current users are used to, and new users will run from like
>   it was a flaming building. (just my not so humble opinion)
I agree. I think its important to consider who are 'users'.
        Programmer types, including many current users who are here, other
technically proficient people, developers - latex is fine.


With the next version, any text-based format will be reasonably
supportable including templates.  This will include XML by using the
PI part of the specification (section 2.6 of the W3C draft).


        Documentation writers here - well I for one am unlikely be able to take
the time to learn latex/tex, unless someone can show me a fasttrack to
learn enough to make it run. And that I seriously doubt, as I expect
people knowledgeable in it to say 'Here its really easy', and I say
'What isn't once you know it.'


This actually doesn't matter much.  So this post is largely in the
spirit of suggesitng that some things aren't accurate in your
portrayal.  I manage a number of extremely large and complex documents
with LaTeX, and I have never found anything that is as easy to use for
this as that.

It is easy if you use a GUI editor.  LyX is easy to use, and if you
want something a bit harder, you can always use Emacs ;-)

With LyX, you wouldn't have to learn it.  Indeed this is actually an
advantage because you only have one supported (cross-platform), client
so you should have no issues with version control.

The big disadvantage is that although LaTeX can be simple, clear, and
edited by a standard editor, it has roughtly the same capacity for
abuse that Perl does because the markup commands are basically macros
and so it is really easy to mix semantic markup with typesetting logic
(though most LaTeX authors of serious documents seem to do an OK job
of avoing this issue).

On the other hand, the learning curve for managing Docbook -> LaTeX
conversion is going to be much higher because although the tags seem
to match OK, there seem to be some areas that are going to take some
learning to make manageable.  There are a lot of document management
features that don't have a 1:1 mapping with Docbook.  For example,
there the <figure> tag maps to the figure, float, and table
environments in LaTeX.  That is OK.  I am sure I will be richer for
it. But it may involve standardizing more rules as time goes on.

Again, either way, I think we should have 1 approved editor, and
automatically disqualify patches which needlessly include a large
amount of the document due to editor variations.

So in the end, it really is six of one and half a dozen of the other.
We could just as easy use XHTML for the content as long as certain
rules are followed.


        Book-keeper types, the main users I think: should be considered
foremost, ahead of the others. Almost none are going to *remotely*
understand how to do all this programming stuff to make even the
slightest change to a template using latex.


You don't expect these people to learn Docbook either do you? Nor
would you expect these people to learn how to write ODF files by hand,
or Word XML files, or the like.

And for revision control purposes, I think it is a *huge* mistake to
support multiple different editors.  So the question is whether you
have *one* good editor we can standardize on.

So all the objections really are irrelevant to the discussion until we
decide what editor we want to standardize on.  If ease of use is what
is important, we need to consider the editor first, and the format
later.  Just MHO.  The format is *only important* insofar as ensuring
it has enough semantic richness to support all the formats we want to
support.  Once we agree on that point, we should look at editors.  And
we should standardize on *one* editor that supports one sufficiently
rich format.


I repeat though: this thread is about documentation/faqs. I do not see
that this should have any relationship to the system printing, reports
etc and whatever mechanism is used there for users to make changes. That
is a total different issue. Documentation development infrastructure is
for programmer types and document writers. The system printing needs to
keep book-keepers and their capabilities in mind. Time and again I see
people here confusing who uses are.


See my points above.

All o the *practical* points being made about LaTeX affect Docbook
equally.  As I say, we need to look at Docbook and LaTeX editors and
select *one* editor that we can standardize on for the purpose of
supporting users.

Altnernatively we can store it in XHTML fragments in a CMS and then
pull it together and organize it into LaTeX and/or Docbook documents.
Honestly, this solution seems to meet people's stated goals better
than either Docbook or LaTeX as a primary format.  But this still
requires using at least one of these formats for managing large
documents because XHTML misses *some* of the semantic constructs
required.

Best Wishes,
Chris Travers