Was using LaTeX a bad move?

Gyroplast · 2003-10-25 11:05:22

Greetings, fellow writers.

Now as I'm finally back into action (more or less) and trying to catch up with all the little changes and nitty-gritty I promised to do, something disturbing occured to me, which might be obvious to most already: Using LaTeX as the official tool to create Arch's documentation was a shot in our collective foot in more than one way.

While LaTeX certainly is able to produce wonderful postscript/pdf output in unreached quality, it's complexity has a great potential to hamper the creation of volunteer docs. It's like using emacs to write your shopping list, if you get my drift.
What use is a undoubtly powerful typesetting tool if you need to study it for a couple of weeks until you get satisfying results? The situation is made worse if I take into account that documentation thrives on the work of lots of volunteers, often only wanting to translate a document and not bother with the nitty-gritty of some obscure program syntax just to get the special characters right (do I see a nod from netkrash, sud_crow et al?).

To cut a long story short, I think this whole LaTeX idea was a total boner on my part, and I wanted to hear some opinions on this issue.

My suggestion now would be to let us come up with a tool/markup language to create all of Arch's documentation that:
- is easy to use, even to the uninitiated
- allows generation of (at least) HTML/XML and plain text
- allows full internationalisation (even chinese/korean/etc. characters)
- has a small footprint (tetex + friends are quite an install just to write a small howto)

That's what I'd consider necessary, and LaTeX kinda fails all but the second point.
Before we dive into looking for tools, did I miss to qualify anything necessary? Do you feel something else must be fulfilled before a tool can be deemed acceptable?

Thanks for your input,
Dennis

Jagged · 2003-10-25 14:55:06

I know OO uses an XML structure in its native documents... if that helps any

andy · 2003-10-25 15:03:02

I already asked myself where you have been :-)

On topic : I, as a LeTeX pro, have to vote for Latex, of course :-) ... but then again, I'm not involed in the documentation of AL.

I was thinking of a possible simplification, but don't think it's that great anymore. Nevertheless, I will post it, maybe it gives some food for thought :

You could use input statements to include more or less text-only parts which then can "easily" be translated. And then the difficult Latex structure hardly needs to be touched.

red_over_blue · 2003-10-25 15:32:37

I use LaTeX as well and think it is great. I use it for all my typesetting and only use OOo if I have to open someone else's word doc. I was also thinking of something along the lines of what andy suggested.

The biggest problem I see with trying to have docs in LaTeX without actually using LaTeX (having someone submit a text doc that is parsed to create a LaTeX file) is that unless the submitter knows how to use LaTeX, they can't see what their doc looks like. If they try to run whatever parser the devs come up with and it fails, then they are SOL. Finally, if they did know how to write LaTeX, they would have just written a .tex in the first place anyway.

I have thought of a couple ways to allow the continued use of LaTeX with some simplification, but they all fail the above problem. Also, since LaTeX fails most of the criteria layed out in Gyroplast's initial post, I think that my suggestions would just be an excuse to keep use LaTeX, rather than the "best" solution.

Gyroplast · 2003-10-25 21:44:51

So may I generally assume that the four points I suggested as requirements really are? If so, would it be ethically acceptable to think along the lines of an XML subset, like Gentoo uses for it's docs? The XSLT parser and XML2 lib aren't too heavy, footprint wise, and a small, well-explained subset of tags should fulfill the needs quite well. Unfortunately I never really used anything beyond HTML4.01 Strict, so the whole XSLT enchilada would be new to me, and somehow I cannot quite disable the "CAUTION, HYPE!" warning bells in my head. Anyone got experiences with that or other ideas?

Another issue is cooperative working on the docs; I have not yet found a clean and easy way to supply a changelog to translators, for example, but then I'm lacking competence in regards to usage of a CVS. Most likely I'm just overlooking something. Care to enlighten me?

fnord,
Dennis

Xentac · 2003-10-26 01:14:14

I think using diff would work for the most part. 'diff -u <old docs> <new docs>' This gives a patch file which most developers are used to, but more importantly it gives the old line and the new line (and tells you where abouts the lines were changed). What more do you need than that?

Mork II · 2003-10-26 08:54:27

I don't mind LaTeX. I don't understand it, but I figured it would work to simply replace the english words with any language of choice and leave the tags alone.

Btw, the swedish translation I'm working on is about 5% done. That took an hour to do so in theory the translation should be ready when I get an weekend off to work on it. However school and other projects tend to get in the way.

//Edit: The translation was 5% ready. Unfortunatly it was stored in the same dierectory as all my other projects. A directory wich I - in a flurry of destructive cleanliness - happened to erase last week. It seems that backups do have their place even on an desktop machine. //

farphel · 2003-10-26 14:11:19

Why not keep LaTex, but just write a simple Arch-doc-HOWTO that can go on the main web site under the Developer section (or a link inside the main Doc)?

I'm sure that there is a standard 'template' of LaTex formatting tags the documentation team uses, right? The Arch-doc-HOWTO could just outline the documentation process for the curious/volunteers. Here's what you need to install... Use these formatting tags... Run these commands to produce HTML/XML/etc... Submit docs to...

I've only started dabbling in LaTex and do find it a bit complex and intimidating, but it's not rocket science. A brief HOWTO would be enough to get most users up and running quickly, IMO.

nifan · 2003-10-26 20:46:57

actually i've been translating arch docs to portuguese (me and jlvsimoes) and i found out that LaTeX is a bit dificult, but using Lyx to edit the source docs it was kind of easy. But i realise it would much easier to use HTML/XML. But whatever you use ill use it
i hope i the next week or so i get the right mood to review the translation and send it to dennis, at least i hope so

sud_crow · 2003-10-27 13:33:35

What use is a undoubtly powerful typesetting tool if you need to study it for a couple of weeks until you get satisfying results? The situation is made worse if I take into account that documentation thrives on the work of lots of volunteers, often only wanting to translate a document and not bother with the nitty-gritty of some obscure program syntax just to get the special characters right (do I see a nod from netkrash, sud_crow et al?).

Here's my nod

Actually, i didnt had that many problems while typing, its like any other language, you just ignore tags (or modify some a bit)....

The problem was that there was no guide on how to make the document headers "compliant" with my language, for some reason when the DVI files (and others) where built, they just skipped the special characters.

This was solved with some tips from Netkrash, who supplied the headers for the .tex file.

So, i think we should stay with LaTeX, but i support the documentation idea.
Unless there is something to replace it, wich is really easy to use and mantein, then, its your call.
Also, i dont know XML neither so, if we change to that one, i just hope "not to" run into the same trouble, coz i dont know who will help me then.

red_over_blue · 2003-11-01 06:23:05

Maybe we should look at texinfo

Texinfo is the official documentation format of the GNU project......
Texinfo uses a single source file to produce output in a number of formats, both online and printed (dvi, info, html, xml, etc.). This means that instead of writing different documents for online information and another for a printed manual, you need write only one document. And when the work is revised, you need revise only that one document.

hughchen · 2003-12-01 08:38:31

Gyroplast wrote:

- is easy to use, even to the uninitiated
- allows generation of (at least) HTML/XML and plain text
- allows full internationalisation (even chinese/korean/etc. characters)
- has a small footprint (tetex + friends are quite an install just to write a small howto)
Dennis

Hi,I'd like to help translate the ArchLinux docs into
chinese.but unfortunately,I don't know how to make LaTeX
support chinese,so I think it's really important choosing a
document/typesetting tool to meet the above requirements.

kpiche · 2004-05-21 12:15:37

I've written some DocBook documentation myself and find it useful. I like how documentation can be modularized and you can define macros - kind of like programming. I've never used TeX myself so I can't comment on its features but I've heard its powerful. I've always felt that there were too many documentation "standards"; why use texinfo when there's html and vice versa.

Admittedly having to learn TeX to contribute documentation can be a large entry barrier for the casual contributor. A quick search on Freshmeat though shows a fair number of "text to something else" projects such as "txt2html", "txt2tags", and "remark". So a contributor could write in plain text and use '*' to create bullet lists for example.

Or you could just tell people to use WYSIWYG tools like LyX or conglomerate.

Dusty · 2004-05-21 15:32:25

We've defined a new standard using Strict XHTML. It's simple and doesn't require learning any new languages for most people. This will be the standard.

The standard will be added to official documentation "soon".

Dusty

Arch Linux

#1 2003-10-25 11:05:22

Was using LaTeX a bad move?

#2 2003-10-25 14:55:06

Re: Was using LaTeX a bad move?

#3 2003-10-25 15:03:02

Re: Was using LaTeX a bad move?

#4 2003-10-25 15:32:37

Re: Was using LaTeX a bad move?

#5 2003-10-25 21:44:51

Re: Was using LaTeX a bad move?

#6 2003-10-26 01:14:14

Re: Was using LaTeX a bad move?

#7 2003-10-26 08:54:27

Re: Was using LaTeX a bad move?

#8 2003-10-26 14:11:19

Re: Was using LaTeX a bad move?

#9 2003-10-26 20:46:57

Re: Was using LaTeX a bad move?

#10 2003-10-27 13:33:35

Re: Was using LaTeX a bad move?

#11 2003-11-01 06:23:05

Re: Was using LaTeX a bad move?

#12 2003-12-01 08:38:31

Re: Was using LaTeX a bad move?

#13 2004-05-21 12:15:37

Re: Was using LaTeX a bad move?

#14 2004-05-21 15:32:25

Re: Was using LaTeX a bad move?

Board footer