NetBSD-Docs archive

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

Re: migrating the NetBSD users guide to the wiki

I am also anti-markdown / anti-wiki format for long texts. Its 
formatting techiques are confusing and weak. I spent a long time 
generating a ~100 page PDF in markdown using ikiwiki. I had to go 
through lots of jumps to get it formatted nicely (to PDF via markdown to 
HTML to LaTeX), do indexing and cross-references, literal layouts with 
formatting, and the wiki source itself became a mess. It was no longer 
very readable as "plain text" for me. (And reading nroff, latex, or 
docbook is sometimes easier.)

I have worked with thousands of printed pages based on LaTeX and Docbook 
without using any knowledgeable word processor. It can also be difficult 
to read and edit, but for me I much prefer the sanity. I like how I can 
identify different things using special tags or syntax, do indexing, 
cross-references, and citations (as an example of some things that are 
very difficult with markdown and wiki).

While I prefer LaTeX, I do like how docbook catches my mistakes 
better. (Someday, I may try to do an entire book using nroff and some 

That said since I haven't been participating in the users guide (and 
pkgsrc guide lately), my vote would be for the largest contributors to 
make their decisions.

To change the topic a little, it would be awesome if we had some 
definite goal for the NetBSD Guide and drive it there, like a real book 
printing.  If printed book was a real goal, then maybe the question of 
this thread would be answered.

Thank you so much for your documentation clean ups!

echo V nz ybbxvat sbe grpu erivrj bs n csFrafr obbx. | \
 tr "VFnoprstuvxyzabcefgij" "ISabcefghiklmnoprstvw"

Home | Main Index | Thread Index | Old Index