Hi,
On Mon, Mar 02, 2009 at 08:07:08PM +0800, FinalBSD wrote:
> Hi,
> Yes Alexander, actually I wrote this by XML and compiled by DocBook
> tools,
> SGML here just means Docbook :), LaTeX is really the best for wrtting
> tecnical
> docs, but it's also complicated and need much to write.
>
> I'm sorry I just finished part of the configuration guide, there maybe many
> errors, and I will finish it soon.
I've seen your work, and I appreciate that you have been working on
this. But let me put up straigt : I definitely *do not* want to write
the doc in a more complex format for several reasons :
- writing doc takes time, a lot of time, about as much as the code
itself. Using richer formats means even more time, and that's out
of question.
- when writing doc, you need to keep a focus on the content and not
on meta-data, tags and such which are very disturbing.
- everyone can write text files, very few people will know whatever
language or convention is used, so I don't want to put such a
restriction to contributions.
- a text file can always be read. You can even print it if you want.
Other formats often require a decoder which is not always suited
for reading via a remote terminal for instance.
However, if I tried to stick to a properly formatted doc, it's also
because I'd like to be able to pass it through a converter which
automatically produces the expected output. I have been asked for
HTML and other formats already. In fact, I don't care. The most
important is that the source format remains parsable to produce
those outputs.
I'd encourage the writing of an awk script (or even perl even if
less portable) to convert a text doc to a [put your format here] doc.
I even agree to fix minor indentation or alignment bugs, and possibly
adjust some of the current conventions if some are too hard to figure
out.
But my position will remain very clear on this matter : the hard work
must be for the machine, not for the author.
Regards,
Willy
