Preferred documentation tool?

Submitted by JohnMG on Thu 8 Feb 2007

Tags: , ,

 

DocBook  <-> 20%98 votes
groff  <-> 1%6 votes
LaTeX  <-> 32%158 votes
Plain TeX  <-> 2%11 votes
POD  <-> 1%9 votes
Texinfo  <-> 1%7 votes
just a text file  <-> 35%171 votes
other  <-> 5%26 votes
Total 486 votes

<<< WM or Desktop on Debian? Which handed are you? >>>

#1
Re: Preferred documentation tool?
Posted by lpenz (200.213.xx.xx) on Thu 8 Feb 2007 at 15:27
[ Send Message ]
txt2tags (http://txt2tags.sf.net) all the way!
Clean markups and renders a great variety of formats.

[ Parent ]

#2
Re: Preferred documentation tool?
Posted by Steve (62.30.xx.xx) on Thu 8 Feb 2007 at 20:43
[ Send Message | View Steve's Scratchpad | View Weblogs ]
Very nice tool, and simple to get started with. I've written a little script to recursively process a collection of .t2t files and create corresponding output HTML. It works well - but there is one significant thing missing which rules it out for me.

You cannot use conditionals, nor can you add code to the templates. So there is no way I can see that I could add class="blah" to link targets dynamically.

I use this kind of thing a lot for menus, eg:

<ul id="menu">
<li><a href="1.html">Page One</a></li>
<li><a href="2.html" class="current">Page Two</a></li>
</ul>

Steve

[ Parent ]

#3
Re: Preferred documentation tool?
Posted by lpenz (200.213.xx.xx) on Fri 9 Feb 2007 at 13:27
[ Send Message ]
Yeah, for that you need some hacking, as far as I can tell.

For instance, the very page on http://txt2tags.sf.net/ is made in txt2tags and uses this sort of stuff (just see the footer on the main page).

postproc and preproc are your friends.

For me, as I usually write documents for the sake of documentation, the possibility to just read a clean markup, or print a PDF, or provide a web page, is wonderfull.

[ Parent ]

#4
Re: Preferred documentation tool?
Posted by Steve (80.68.xx.xx) on Fri 9 Feb 2007 at 13:33
[ Send Message | View Steve's Scratchpad | View Weblogs ]

Ahh looking at their code is instructive. They give each link on the menu an ID, then set "<body id=blah>" to do the styling on the menu.

I will experiment with this myself.

Steve

[ Parent ]

#5
Re: Preferred documentation tool?
Posted by JohnMG (69.177.xx.xx) on Fri 9 Feb 2007 at 17:46
[ Send Message ]
Very interesting results. I'd expected a larger spread, and also expected a much greater number of folks using Perl POD. Lately, I find myself using POD more and more, mostly because it's so darn simple, and because I can so easily render it with the perldoc command, as well as convert it with the pod2whatever tools. I like Texinfo too, but it requires a certain amount of extraneous commands in the right order to make your docs come out right. I hate to say it but the simplicity of POD is tough to beat.

[ Parent ]

#6
Re: Preferred documentation tool?
Posted by Anonymous (213.164.xx.xx) on Tue 13 Feb 2007 at 10:03
Definitely a wiki.

(And an extra sentence here to get around that damned bayesian filter.)

[ Parent ]

#7
Re: Preferred documentation tool?
Posted by Anonymous (213.224.xx.xx) on Tue 13 Feb 2007 at 18:38
Myes, this was in my mind too, but a Wiki doesn't have the same layout possibilities as for instance LaTeX. I also remember me documenting a lot of work on Confluence (most likely the top of commercial wikis), and each update of the server made it interpret pages with "advanced tables" differently. Documentation that had to go to the client had to be reworked every time...

[ Parent ]

#10
Re: Preferred documentation tool?
Posted by Anonymous (213.164.xx.xx) on Wed 14 Feb 2007 at 15:16
I've never had this problem. I use pmwiki and it works great.

I'm surprised that layout is so important for you though..

[ Parent ]

#12
Re: Preferred documentation tool?
Posted by Anonymous (213.224.xx.xx) on Wed 14 Feb 2007 at 20:19
> I'm surprised that layout is so important for you though..

In the company where I worked, we gave the customer a readonly account to enter certain spaces, so the pages needed a more or less professional look. Also I feel that nice docs make it so much more appealing to read them :).

[ Parent ]

#8
Re: Preferred documentation tool?
Posted by felix_stegerman (83.162.xx.xx) on Tue 13 Feb 2007 at 20:18
[ Send Message ]
Simple documentation: text files;
Perl documentation: (inline) POD (w/ Pod::Usage);
anything mathematical: LaTeX.


- Felix

-- 
Felix C. Stegerman <flx@obfusk.net> [http://obfusk.net]
~ "Any sufficiently advanced bug is indistinguishable from a feature."
~   -- R. Kulawiec
~ vim: set ft=mail tw=70 sw=2 sts=2 et:

[ Parent ]

#9
Re: Preferred documentation tool?
Posted by loke (213.136.xx.xx) on Wed 14 Feb 2007 at 09:53
[ Send Message ]
why wasnt wiki an alternativ ?

[ Parent ]

#13
Re: Preferred documentation tool?
Posted by chris (213.187.xx.xx) on Wed 14 Feb 2007 at 21:07
[ Send Message ]
Perhaps because there are only up to 8 options for a poll and the submitter ran out?

[ Parent ]

#14
Re: Preferred documentation tool?
Posted by JohnMG (67.86.xx.xx) on Thu 15 Feb 2007 at 01:12
[ Send Message ]
> why wasnt wiki an alternativ ?

Wiki's often use different markup formats. For example, Markdown, Textile, the MoinMoin style, etc. Another example of a markup like that is txt2tags which lpenz mentioned. So, I guess all of those would fit into ``other''.

[ Parent ]

#11
Re: Preferred documentation tool?
Posted by Anonymous (86.40.xx.xx) on Wed 14 Feb 2007 at 18:05
I voted 'other' cos there was no wiki option

[ Parent ]

User Login

Username:

Password:

[ Advanced Login ]

Register Account

Quick Site Search

Poll Archive

View Prior Polls