[Nut-upsdev] Help with AsciiDoc man pages

[Charles Lepple]

On Sun, Oct 11, 2009 at 6:49 PM, Alexander Gordeev
<lasaine at lvk.cs.msu.su> wrote:
> I've just commited a converted megatec_usb man page. Is it ok?
> I'm going to convert at least all megatec-related man pages (blazer
> ones two).

Alexander,

Thank you! I was only looking for some help reviewing the converted
pages, but help with the actual conversion is appreciated as well.

> BTW, I'm getting this error when I type 'make':
> /usr/bin/a2x -f manpage --attribute nutversion="2.4.1" `basename hosts.conf.txt`
> ERROR: hosts.conf.txt: line 10: second section must be named SYNOPSIS
> a2x: failed: asciidoc --doctype=manpage  -a "nutversion=2.4.1" -d manpage -b docbook "hosts.conf.txt"
>
> If I insert SYNOPSIS section everything is OK. Sure this section is not
> needed for configuration files.

Hmm, in the version of asciidoc on the buildmaster (8.4.5), this error
does not occur. I agree - it does not make sense for a configuration
file.

> P.S. It would be cool to convert everything automatically. Maybe
> writing another one groff postprocessor, which will do the job, is not
> very hard? I haven't looked at the code yet.

I thought about trying doclifter (which doesn't quite get us to
AsciiDoc, but "lifts" from *roff to a more semantic markup). However,
I wanted to convert the first few man pages by hand to see what needed
to be done. IMHO we would probably spend more time tweaking the tool;
plus, this gives us a chance to re-read the man pages to make sure
they still hold true.

I have a few vi s/// commands stored up which convert things like
"\(hy" and the "\fB"/"\fR" around man page links, but a lot of them
need to be verified afterwards (also, different people have very
different styles for indented text and list markup).

Note that the AsciiDoc equivalent of "\(hy" is just "-", and I am just
being lazy and using "--" for both an "en dash" (used for ranges of
numbers) and for an "em dash"--as used here to separate clauses in a
sentence. Also, in the contents of the name section, we should
continue to use "nameofprogram - one line description" with a
space-hyphen-space so that AsciiDoc splits that up correctly.

Along those lines, the "linknut:" macro probably only makes sense for
man pages that we generate. We might want to have a different macro
for external man pages like "regex(7)" which we do not include in NUT.

Thanks again,

-- 
- Charles Lepple