On 01:39 12 Aug 2002, Dominik Vogt <[EMAIL PROTECTED]> wrote:
| On Sat, Aug 10, 2002 at 11:44:35AM +1000, Cameron Simpson wrote:
| > What kind of infrastructure did you have in mind?
| > I'm personally very fond of POD as a source format for most stuff, since
| > it's unassuming and very easy to edit and read, and readily generates
| > other formats. Does require perl though.
|
| I'm a complete newbie inrespect to documentation formats. Some
| basic requirements are:
|
| - Must be convertible to various other formats (man page, ps,
| html and possible GNU Texinfo) and must look good in these
| formats.
It does all these, except texinfo, but it will emit latex if you really
care.
| - The tools must works on any system and should run out of the
| box.
if they have perl, definitely.
| Everybody must be able to edit the documentation.
Yes. It's damn near plain text with very simple and unintrusive markup.
| - The format should be reasonably easy to edit without any tools
| other than a text editor.
Yep. That's what I like about it.
| Perl is no problem, we already use it.
Cool.
Will have to address the 2nd half of your message later.
Meanwhile, "man perlpod" will describe the format for you. Here's a shell
script with its own manual page inlined (I pull it out and format with
a script):
http://www.zip.com.au/~cs/scripts/lz
Here's the HTML page that makes.
http://www.zip.com.au/~cs/man/lz.1.html
The manual page looks exactly like a regular manual page.
The leading hashes aren't part of the format - they're just shell comments
to hide the POD from the shell. Typical pod is:
=head1 A Heading
Here's an example paragraph
that will be filled (line flowed) by whatever backend format gets used.
Here's a reference to the fvwm(1) manual page.
Here's some literal (unfilled) text:
DestroyFunc foo
AddToFunc foo Next
Here's the next paragraph with a B<bold> word.
Very user friendly.
--
Cameron Simpson, DoD#743 [EMAIL PROTECTED] http://www.zip.com.au/~cs/
Academics get paid for being clever, not for being right. - Donald Norman
--
Visit the official FVWM web page at <URL: http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm" in the body of a
message to [EMAIL PROTECTED]
To report problems, send mail to [EMAIL PROTECTED]
