good chemistry is complicated,and a little bit messy -LW PerlMonks

### Creating Books and Manuals with Perl

by skazat (Hermit)
 on Sep 10, 2002 at 02:55 UTC ( #196512=perlmeditation: print w/ replies, xml ) Need Help??

Hello Fellow Monks,

I'm about to start writing a book/manual of sorts, on a Perl project that I have been working for a little over 2 1/2 years. The program itself has gotten a nice little following and the purpose of the book is to fund additional work on the program (or rather, justify me working on the program for free) and to also help myself out while attending college full time. Perhaps, 33% of the book is already written in one form or another and my question really is,

How should I go about managing and updating this manual?

Since the book/manual is going to be about a constantly changing thing (the program) it seems only natural to have a system where I can easily regenerate a new version of the book.

Because of the size of the development base (only me) and my distribution choice, the book/manual itself will most likely be created in HTML, with a possible PDF version in the future.

Before I delve into making my own manual-making tool, I wanted to ask for the advice of the community into seeing if there are already tools available for this task. I look at siteslike mysql.com and postgresql.org and noticed that their manuals are all auto-generated.

My first thought on going about this was to use POD as the format to write the manual in and then write a small Perl program that will make an index of all my POD documents and then make a nice index and table of contents from those POD documents. I've already done something like this for the support documetation I already have for the program:

In this case, it made a lot of sense to do it this way, since most of what's here is actually embedded pod inside Modules and things like that. But, since I'm writting a manual/book which won't be embedded in any sort of code, would it still be a good idea to use POD?

My other idea was to use a form of XML, or even just XHTML. The benifits of this being flexibility, the fact that I don't have to parse what I've written into HTML and the chance that if my XHTML is way strict, I can import the files into a program like InDesign, which would then sputter back a PDF for me. The bad thing about this is the amount of complexity of actually writing the manual goes way up, since instead of using way simple POD directives, I get to make sure all my tags have end tags, my tags are nested correctly, everything everyone here is very used to. I would rather take the time I have to write the book. Doing everything in XHTML may even make it harder to generate an index and table of contents for the books, since I'll have to parse out the XHTML tags I want.

So, I had the divine thought that this problem has definetly been solved before and that maybe a simple, Perl solution has been created. If not, any ideas are greatly appreciated. My main concerns are simplicity; if possible, I want to be writing/editing the docs in a text editor and I need to have the ability to at least make an HTML version of the docs quickly and whenever I want.

Thanks, everyone!

Edited: ~Wed Sep 11 23:27:09 2002 (GMT) by footpad: Moved to Meditations, per Consideration.

Replies are listed 'Best First'.
Re: Creating Books and Manuals with Perl
by Zaxo (Archbishop) on Sep 10, 2002 at 03:15 UTC
And if you use docbook, you might be able to get
O'Reilly to publish it. :-)
Re: Creating Books and Manuals with Perl
by cxbast (Novice) on Sep 10, 2002 at 04:02 UTC
You may want to check out Tex and Latex which are open source standards for writing scientific and other types of manuals including Readers Digest. Tex gives you the flexibility of putting anything you want on a page without the difficulty of coding it in postscript. Another nice feature is that it is a language that can be data driven so there are no point and clicks required to keep your manual up to date. We use it to generate postscript and pdf reports with graphics etc... We have produced 5000 page reports, so volume it can handle. Go to the following site: http://www.ctan.org/find.html and use the file search to look for gentle.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 www.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

Re: Creating Books and Manuals with Perl
by Aristotle (Chancellor) on Sep 10, 2002 at 10:02 UTC

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.

Re: Creating Books and Manuals with Perl
by bart (Canon) on Sep 10, 2002 at 10:35 UTC
You might reconsider using SDF (Simple Document Format). It's a format originally based on POD, plus a set of tools written in Perl. The original home page is gone, but this mailing list message says you can still find it on CPAN. And you can.

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

Re: Creating Books and Manuals with Perl
by Joost (Canon) on Sep 10, 2002 at 10:03 UTC
Well, I use POD for my documentation efforts, and I like it because of the speed in which I can type it, and the easy way of generating other formats from the source file.

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):

Re: Creating Books and Manuals with Perl
by Matts (Deacon) on Sep 10, 2002 at 12:56 UTC
The only hesitation I'd have with POD is that it's not terribly extensible at the text level.

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.
Re: Creating Books and Manuals with Perl
by ash (Monk) on Sep 10, 2002 at 09:28 UTC
Anyone have any guides to documenting Perl with LaTeX?
I've got two books on LaTeX written by Leslie Lamport and it doesn't exactly come clear how to embed code (except pascal) into LaTeX.

--

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}

The result would look like this:

#!/usr/bin/perl for (1..10) { print "Hello, world\n"; }

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 ;^)

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

Re: Creating Books and Manuals with Perl
by John M. Dlugosz (Monsignor) on Sep 10, 2002 at 14:44 UTC
Re: Creating Books and Manuals with Perl (Pod, LyX and TCM)
by Flexx (Pilgrim) on Sep 28, 2002 at 23:28 UTC

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

Create A New User
Node Status?
node history
Node Type: perlmeditation [id://196512]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (5)
As of 2016-08-26 04:25 GMT
Sections?
Information?
Find Nodes?
Leftovers?
Voting Booth?
The best thing I ever won in a lottery was:

Results (365 votes). Check out past polls.