You are not logged in.

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

Gyroplast
Member
From: Germany
Registered: 2002-09-03
Posts: 166
Website

Was using LaTeX a bad move?

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. wink
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. tongue
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


"That's the problem with good advice. Nobody wants to hear it."
-- Dogbert

Offline

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

Jagged
Member
From: Blacksburg, VA
Registered: 2003-07-18
Posts: 153

Re: Was using LaTeX a bad move?

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


Nkawtg...n!

Offline

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

andy
Member
From: Germany
Registered: 2002-10-11
Posts: 374

Re: Was using LaTeX a bad move?

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.

Offline

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

red_over_blue
Member
Registered: 2003-07-19
Posts: 152

Re: Was using LaTeX a bad move?

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.


Don't forget to post your PKGBUILD in your thread when you announce a new package in incoming.
see HERE for details

Offline

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

Gyroplast
Member
From: Germany
Registered: 2002-09-03
Posts: 166
Website

Re: Was using LaTeX a bad move?

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


"That's the problem with good advice. Nobody wants to hear it."
-- Dogbert

Offline

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

Xentac
Forum Fellow
From: Victoria, BC
Registered: 2003-01-17
Posts: 1,797
Website

Re: Was using LaTeX a bad move?

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?


I have discovered that all of mans unhappiness derives from only one source, not being able to sit quietly in a room
- Blaise Pascal

Offline

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

Mork II
Member
From: Visby, Sweden
Registered: 2003-05-14
Posts: 87

Re: Was using LaTeX a bad move?

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. //

Offline

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

farphel
Forum Fellow
From: New Hampshire - USA
Registered: 2003-09-18
Posts: 250
Website

Re: Was using LaTeX a bad move?

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.


Follow the link below, sign up, and accept one promotional offer.  If I can get five suckers (err... friends) to do this, I'll get a free iPod.  Then you too can try to get a free iPod. Thanks! http://www.freeiPods.com/?r=11363142

Offline

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

nifan
Member
Registered: 2003-04-10
Posts: 102

Re: Was using LaTeX a bad move?

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 tongue
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 smile


______
"Ignorance, the root and the stem of every evil." - Plato

Offline

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

sud_crow
Member
From: Argentina
Registered: 2003-06-30
Posts: 545

Re: Was using LaTeX a bad move?

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 wink


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. wink


Leonardo Andrés Gallego
www.archlinux-es.org || Comunidad Hispana de Arch Linux

Offline

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

red_over_blue
Member
Registered: 2003-07-19
Posts: 152

Re: Was using LaTeX a bad move?

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.


Don't forget to post your PKGBUILD in your thread when you announce a new package in incoming.
see HERE for details

Offline

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

hughchen
Member
From: ShenZhen,GD,China
Registered: 2003-11-06
Posts: 10
Website

Re: Was using LaTeX a bad move?

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.

Offline

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

kpiche
Forum Fellow
From: Ottawa, ON, Canada
Registered: 2004-03-30
Posts: 246
Website

Re: Was using LaTeX a bad move?

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.   smile

Offline

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

Dusty
Schwag Merchant
From: Medicine Hat, Alberta, Canada
Registered: 2004-01-18
Posts: 5,986
Website

Re: Was using LaTeX a bad move?

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". wink

Dusty

Offline

Board footer

Powered by FluxBB