Public SourceMage Discussion List

[Remko van der Vossen <wich AT stack.nl>]

On Fri, Aug 29, 2008 at 07:54:52AM -0500, David Kowis wrote:
>> I haven't seen the IRC discussion, but I would raise a note of caution
>> on the point of DocBook and LaTeX.  I like LaTeX and I would still be
>> hesitant to use it in this type of situation.  Anyone can throw together
>> some docs in MoinMoin with a few minutes work.  Even someone familiar
>> with LaTeX is going to have to invest considerably more time in putting
>> together documentation.
>>
>> The more work you require to create and update the documentation, the
>> less documentation you're going to get.  :-)
>>
>
> Yeah. I agree with this. Keep the bar to entry low. Where's our  
> Spellwriter's handbook? Oh it's in LaTeX supoosedly still under  
> development by sandalle. How long has it been there? Years...
>
> I don't think doing docs in anything other than simple plain text is a  
> good idea. (wikisyntax is okay)

Actually I would very much be in favour of LaTeX documentation, there
are quite a number of tools to create other forms from the LaTeX (html
single page, multi page and framed, man pages, texinfo pages and txt) in
addition to the regular dvi, ps and pdf.

I feel LaTeX is many times more transparent than wiki markup, I mean,
what's easier to understand \textbf{foobar} or '''foobar'''. It will
only take a little to realise bf stands for boldface and once you know
it you won't forget it because of the clear contextual link. In the case
of wiki markup however I have to look up the insane markup each and and
every time. And is most definately something that is holding me back
from contributing more to the wiki/documentation.

Uhmn, and we have a LaTeX spellwriter's handbook under constrution? Why
don't I know about that? Given that I don't know about it I'm hazarding
a guess that other new developers also didn't know about this... And
furthermore is this in a git repo somewhere so that we can all
contribute? If there isn't I'm not that surprised that it didn't get
very far, especially given the apparent lack of "marketing" it has
gotten. Writing such a document alone is a very big task, especially
considering all the other tasks sandalle performs within sourcemage, let
alone outside of it.

LaTeX is the perfect means to do this, LaTeX supports very good command
definitions and inclusion commands like include and input which allow a
very good seperation of the various parts of the project. Also one can
easily use a makefile to handle the building of various versions of the
documentation. We could easily set up a daily (or whatever) automated
checkout and build of for instance the html and pdf so that they may be
available on the sourcemage website.

I have to disagree that you need much more time to write documentation
in the case of LaTeX, what markup do you use in the wiki, simple things
like bold, italic, teletype faces and stuff like section headings and
bulleted and enumerated lists. All this stuff is the most basic of
things in latex, it doesn't require any special knowledge to create any
bit of documentation in the latex format. In fact in LaTeX we could also
create our own global commands like \spell{foo}, \spellfile{bar},
\code{foobar}, etc. which gives us a consistent markup over all
SourceMage documentation, which we can easily modify if we would wish so
to boot. (Note that I don't know if you can define your own "commands"
in moinmoin, perhaps you can.)

Much more than the basic LaTeX markup you will never need, or only in
very special cases, or in something like one of our custom commands, but
those are special cases which can be handled by the more LaTeX savvy,
more than 95% of the documentation is basic stuff which can be written
by anyone, including those with next to zero LaTeX knowledge. The only
thing that gets trickier in a basic document is the stuff outside the
document itself, i.e. setting up the page layout, choosing the
appropriate options, document class, defining the custom commands, that
kind of thing, but you don't need to do that each time.

We could either use a template for that, which you can simply \input
into another latex document. Or, in my opinion the better option, don't
create a seperate latex document for each and every piece of
documentation, but instead create the grand and holy sourcemage book (or
perhaps a small set of books), which includes different chapters on
different topics we wish to document. Then for instance if you want to
write a FAQ "foo", you \input that file in the FAQ chapter file, and
only need to do the basic latex markup in the "foo" file. Then only the
"global" file of each book needs any special stuff like document
classes, packages, options, page layout and our global command
definitions. The rest of the documentation is simply \input-ted.

I've worked on collaborative LaTeX documents in quite a number of
different university projects, with groups ranging from 3-10 people and
it works perfectly. We've even had people in our groups which knew no
LaTeX whatsoever when we began, but they were able to contribute from
the get go, since they only needed to know the basic stuff like
\section, \subsection, \textbf, \textit, \item and the itemize and
enumerate environments.

Regards,

Remko van der Vossen

Attachment: pgpGUxPZiRjo1.pgp
Description: PGP signature