You might consider docbook as markup. There are transformations to any format you might want. A DocBook-OpenJade-SGML-XML HOWTO is available.

After Compline,
Zaxo

And if you use docbook, you might be able to get
O'Reilly to publish it. :-)

I recommend A Gentle Introduction to TeX (PDF). If you read this document you will be able to get an idea if TeX is what you are looking for. If it is then look around in ctan.org for how to get started.

I agree that LaTeX is a great choice for this task.

You might even look at a Literate-Programming (LP) tool such as noweb to mix your source code and documentation. In my opinion this makes updating both, the code and the docu, a lot easier.
You'll find interesting things on LP on this site and the homepage of noweb.

Enjoy writing!
weini

I think POD is an excellent choice for the task. It was perfectly sufficient for Camel 3 to be written in it, after all; a perfect flyweight markup language for documentation or technical literature. You can embed sequences of foreign markup with the =for directive; for example have a =for html passage that contains a link to an image. There are many, often highly configurable pod2* scripts. Want to have it in actual print? pod2latex will do the job. No need to even mention pod2html. If none of those suit your needs you can roll your own f.ex by throwing POD::Parser and Template Toolkit 2 at the problem for minimum effort and maximum flexibility.

What I love about POD is that it is very basic yet provides all the essential directives: the resulting documents are fully indexable. Formatting directives are reduced to the minimum required, so they translate well to any destination media regardless of what it is.

I would definitely not want to write documentation in XML. That markup language is, IMO, not for human consumption.

POD is underappreciated in my opinion. Quoth podmaster's sig: POD is sexy. ;^)

Makeshifts last the longest.

Also, there are some slides of a recent lecture by Ron Savage, available online.

I made a small script that hacks the output of pod2html into seperate pages with a navigation bar on the side as show in the above link. Script follows (you might need to adapt it a bit if you want to use it):

With POD it's easy enough to add new paragraph level directives using =for and =begin/=end, but there's no way built into POD to add new X<< ... >> directives. Partly because there's only so many single letter directives to go around, and partly because POD parsers just don't support this kind of extensibility.

So if you expect to be using footnotes or endnotes or index hints or any of those sorts of other extended things that need to go at the text level rather than at the paragraph level, I would go with XML. Don't worry about what syntax of XML you use, be it DocBook or XHTML or TEI or invent your own as you go along. It's always easy enough to transform between one syntax or another with XML using XSLT or other transformation tools like a SAX filter.

If you feel you can live without those features, then I'd say go with POD. It's really easy to author, and quite readable from an editing perspective, and when it comes down to rendering it to different formats, the tools are pretty much second to none.

With POD it's easy enough to add new paragraph level directives using =for and =begin/=end, but there's no way built into POD to add new X<< ... >> directives. Partly because there's only so many single letter directives to go around, and partly because POD parsers just don't support this kind of extensibility.

Maybe I am just not getting what you mean, but POD is extensible in those ways and more, isn't it?

For instance, Pod::Parser, unless I recall totally wrong, does not care one bit what commands or interior sequences you feed it. You get the comand name, or the letter of the sequence (and lots of other data, like delimiter used), and then it is up to you what to do with it. So whatever you want the commands to do, and whichever commands (as long as they follow normal POD standard) is totally up to you.

Granted, then you can not directly use the core parsers, but let's face it. For the most part, you would need to modify or completely rewrite them anyways, since they are specialized to deal with perl docs, and lots of them do produce output that you need to modify anyways. Pod::HTML is a prime example.

But yes, that would require some extra work, although I suspect most of the modules probably only take subclassing and overriding certain methods, possibly passing whatever you got on to the next level after your amendments.

XML is just fine to use, of course, with one notable 'if': If you have some kind of editor that makes the tags for you, and hides them when typing. XML is humanreadable, yes, for certain values of readable... and writable raw? Ugh.

I think some word processors do save their documents in XML, like AbiWord maybe? I don't recall. But that would be a great start to convert to other formats, of course.

If I misunderstood you, I apologize. :)

---

You have moved into a dark place.
It is pitch black. You are likely to be eaten by a grue.

What you're looking for is the verbatim environment. It's similar to <code>...</code> in HTML and is written like this:

\begin{verbatim}
#!/usr/bin/perl

for (1..10) {
    print "Hello, world\n";
}
\end{verbatim}
[download]

The result would look like this:

#!/usr/bin/perl

for (1..10) {
    print "Hello, world\n";
}
[download]

Also, you may find some of the tutorials here useful if you're in a rush to see if you and LaTeX get along.

— Arien

As I mentioned earlier I use noweb for mixing Perl code and documentation. There's a onepage Guide to using noweb at http://www.eecs.harvard.edu/~nr/noweb/onepage.ps.
I am not good at LaTeX but I understand it and was able to start my documentation work after a few minutes of reading. If you know LaTeX well, you'll be even faster.

What I like in using noweb is the fact that I have just one file to edit. I can then extract the documentation (html, ps, pdf) and the several other files (e.g. perl-script, perl-module, sql-script, makefile). UC: I'm a real fan ;^)

weini

Since you say you have two Lamport's books I suppose you don't have The LaTeX Companion. It explains in good detail a lot of useful LaTeX packages. I definitely reccommend it.

Ciao!
--bronto

# Another Perl edition of a song:
# The End, by The Beatles
END {
  $you->take($love) eq $you->made($love) ;
}

I recommend getting hold of the listings package.

It allows for short code snippets as well as long listings and file inclusions, source highlighting, supports a few dozen languages etc. etc. and even has a switch to display/not display POD in perl files.

Hmm... it might be a nice project to include that in pod2latex...

—John

Hi skazat!

Best advice I can give is: Get yourself a set of tools, and use all of them where appropriate. As long as you write your docs in a sytem that's portable, you'll be fine. It could be SGML/DocBook, XML, LaTeX, POD, HTML, etc. All of them are markup languages, and as such quite interchangable with each other by definition.

Personally, I use and like POD for smaller things. I wouldn't want to use anything else for module reference documentation. It's fine to document your modules, but I'd stay within that scope. I don't write books with it...

When it comes to Whitepapers, Technical Reports and the like, I use LyX. It's a graphical (xforms) WYSIWYM frontend to LaTeX 2e, and runs on X11, OS/2 and Windows/CygWin.

LyX exactly meets my requirements. As an author, I don't want to care (or be constantly tempted) to work on layouts, or formatting. I'd rather hack away on making a good point... ;) LyX does exactly that. It keeps my focus on the document structure and content, and let's me care about how the output actually looks (or which format it's in) only when I want to. It spits out LaTeX (of course), HTML, pdf, DocBook, Postscript. That's pretty much all I need.

Also, don't be scared by LaTeX complexity. You don't need to learn LaTeX to work with LyX. Not at all. However, if you're a bit like me, you'll maybe want to have a look into it. And since I did, I really feel the power under the hood of LyX.

Using Pod2LaTeX, you can easily translate your POD to LaTeX snipplets, which will be integrated into your LyX files with a few mouseclicks. They'll even "assimilate" your documents formatting!

Want grapics, fine, LyX will use almost any format. Math formulae? This is where LaTeX flexxes (heh) it's muscles! I love to have prettyprinted math formulae in my docs. A code snipplet is fine most of the time. But a neat formula often gives a better picutre about what your code does mathematically. Also make sure to get the Algoithms package for LaTeX. While not directly integrated in LyX, you'll learn how to use it with LyX in less than an hour. It'll pretty print your Perl code, with syntax formatting, line numbers, nice headers, list of algorithms page for your appendix, etc.

LyX print (postscript) output is excellent, especially compared to the minimal effort to archive it. You can't do that with Word.. ;)

What are LyX's weaknesses? Bigger tables can be a bit of a hassle, I miss a feature to automatically scale down the font sizes when the table becomes to large to fit (I'm sure there's some LaTeX way of doing so, however). Some things in LyX seem a bit complicated until you get used to them. LaTeX shines through the edges, which might trouble some people, for me however, it became one of LyX's strengths...

Maybe I slid a bit offtopic now, but maybe you want to bear with me. Another tool I really like is TCM (Toolkit for conceptual modelling). I use it for all my diagrams and modelling needs. Using it early in the development cycle not only provided me with diagrams for my docs, but also helped me design things in the first place, since there are diagram types with semantic checks built in.

The general diagram editor is all I need to add some "boxes and elipses with text in them, and some lines and arrows which connect the boxes" diagrams to my whitepapers (indeed, that's all I need to illustrate a problem). It also has a general table tool, that helps when LyX's tables won't suffice. It exports to EPS which is perfectly importable in LyX, and allows for scaling, too.

TCM uses a fully documented plaintext format, which can be automatically generated by some software. You can write Perl modules to dump your data structures as TCM files, if you needed that. If you want to see what TCM can do, read it's online docs. The diagrams you'll find there are made with it, of course.

To sum it up: POD, LyX/LaTeX and TCM are a powerful team, I'd reccomend to anybody who has to write technical documentation.

So long,
Flexx