Re: [RFC] Splitting the man page

On Mon, Nov 15, 2021 at 04:54:09PM +0000, Thomas Adam wrote:
> On Mon, Nov 15, 2021 at 05:13:47PM +0100, Dominik Vogt wrote:
> > 2) The Makefile.am now uses the standard "man1_MANS" file type to
> > describe the generated files.  That should make local installation
> > rules unnecessary.  Not sure whether it also handles the
> > "transform" stuff or not.  For now I've removed it.
>
> We'll need to support the transform stuff, as I know some packagers use it.

Guessed so.  I believe automake + autoconf should support that
automatically in the generated rules, but it needs to be tested.
Anybody here who knows how that works?

> > 3) There's a new, experimental page "fvwm3commands.adoc" which
> > has a header and then just includes the file
> > fvwm3_commands.section.  This file is generated from fvwm3.adoc by
> > extracting all text between the two comments
> >
> >   // BEGIN 'commands'
> >   ...
> >   // END 'commands'
>
> I think this is a good approach.  Something in the back of mind tells me this
> is something which asciidoc(tor) supports, although it's a moot point as this
> is lightweight enough that it's not going to introduce any overhead.

Asciidoctor has an ifdef mechanism.  See attached patch (goes to
the top of the feature branch).  The real manpage source is now in
fvwm3_manpage_source.adoc (better name suggestions welcome).
fvwm3.adoc and fvwm3all.adoc are wrappers.  The asciidoctor call
passes the page name as an attribute that can be checked in the
sources:

  $ asciidoctor ... -a fvwm3 ...
  $ asciidoctor ... -a fvwm3all ...

--snip--
ifdef::fvwm3[]
== LIST OF FVWM COMMANDS

Please refer to the fvwm3commands man page.
endif::[]
ifdef::fvwm3all[]
// BEGIN 'commands'
== LIST OF FVWM COMMANDS
...
...
...
...
...
// END 'commands'
endif::[]
--snip--

> > Seems to do what is intended; "make install" and "make uninstall"
> > work fine, but I haven't tried to build and test a distro from
> > that.
>
> Worked well for me.

Good.  This was all so much trouble in past times.  Now you write
two lines in Makefile.am and that's it.

Ciao

Dominik ^_^  ^_^

--

Dominik Vogt