Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 17/01/2014 16:31, IKEDA Soji a écrit :
> On Fri, 17 Jan 2014 15:32:16 +0100
> Guillaume Rousse <address@concealed> wrote:
>
> > Le 14/01/2014 04:24, IKEDA Soji a écrit :
> > > Hi,
> > >
> > > On Mon, 13 Jan 2014 19:44:52 +0100 (CET)
> > > address@concealed wrote:
> > >
> > > > sympa[10157] trunk/src: [dev] install man page for foobar.pl binary as 
> > > > foobar.pl.X instead of foobar.X, so as keep sympa.8 name free for a generic 
> > > > man page
> > > > Revision 10157 Author rousse Date 2014-01-13 19:44:52 +0100 (lun. 13 janv. 
> > > > 2014)
> > > > Log Message[dev] install man page for foobar.pl binary as foobar.pl.X instead 
> > > > of foobar.X, so as keep sympa.8 name free for a generic man page
> > >
> > > I don't agree to this policy.
> > >
> > > o Generic man page sympa.X may not be put in section 8 (I don't
> > >     know what is "generic", though).  I suppose there are no reason to
> > >     reserve the file name "sympa.8".
> > >
> > > o By previous commit r10156, man pages became directly generated
> > >     from corresponding scripts: Intermediate PODs are no longer used.
> > >     We can take one more step.  If man pages were named as NAME.X,
> > >     makefile will be simplified using suffix rule, then, redundant
> > >     rules such as "sympa.8: sympa.pl" are no longer required.
> > >
> > >     | man8_MANS = archived.8 bounced.8 alias_manager.8 sympa.8
> > >     |
> > >     | .pl.8:
> > >     |   rm -f $@
> > >     |   $(AM_V_GEN)$(POD2MAN) --section=8 --center="sympa $(VERSION)" \
> > >     |   --lax --release="$(VERSION)" $< $@ 
> > >
> > >     [*see also note below]
> > >
> > > o When the NAME section of POD is written as
> > >
> > >     | =head1 NAME
> > >     |
> > >     | sympa, sympa.pl - A Modern Mailing List Manager
> > >
> > >     man page finally generated will indexed both with "sympa" and
> > >     "sympa.pl" regardless to its file name, sympa.8 or sympa.pl.8
> > >     (this is true at least on many Linux distributions).  I suppose
> > >     file names of man pages need not include extension ".pl".
> > Good point. However, I'd prefer than the difference between 'the man
> > page about sympa-the-software' (you suggestion, BTW) and 'the man page
> > about the-main-sympa-executable' isn't just the man section used.
> >
> > Using what I just did, we have:
> > man sympa    -> sympa software global documentation
> > man sympa.pl -> sympa.pl executable specific documentation
> >
> > Using man section, we would habe:
> > man X sympa  -> sympa software global documentation
> > man 8 sympa  -> sympa.pl executable specific documentation
> > man sympa.pl -> an alias for the last one
> >
> > This kind of setup is the reason why I always need 3 attempts to
> > localise the man page refering to the actual crontab format :) Moreover,
> > there is no man section dedicated to generic documentation, AFAIK. The
> > polkit framework documentation, for instance, is located in section 8,
> > the same as polkitd.
>
> I'd noticed it.  Probably generic documentation doesn't suit to
> man page scheme. --- It might be written as particular manual,
> on such as software's web site.
I still think keeping 'man sympa' working, and resulting in something 
else as 'sympa main binary' man page would be helpful. Not necessarily 
to document the whole sympa architecture, but to refers to individual 
additional man page. Something as:

if you're interested in main binary documentation, see 'man sympa.pl'.
if you're interested in sympa setup procedure, see 'man sympa_wizard.pl'
if you're interested in sympa management procedure, see 'man 
sympa_manager.pl' (once the split achieved, of course).

Additionally, it allows to keep shared informations, such as autorship, 
licensing and copyright assignement, in a single place, instead of 
duplicating them in every single man page.

[..]
> > > - Naming of several programs are too generic: "archived", "bounced",
> > >     "bulk", "task_manager", and in addition, "web_help" for
> > >     translation catalog.
> > >     There is a risk of conflict with files come from other packages.
> > >     So in the future, they would be renamed to such as the name with
> > >     "sympa_" prefix ("sympa_archived.pl", "sympa_help.mo" etc.).
> > Absolutly. I'd also like to enforce a final 'd' for all daemons, which
> > would result in the following renaming:
> > * archived.pl     -> sympa_archived.pl
> > * bounced.pl      -> sympa_bounced.pl
> > * bulk.pl         -> sympa_bulkd.pl
> > * task_manager.pl -> sympa_task_managerd.pl
> >
> > Also, instead of filename prefix, we could use a subdirectory under
> > $prefix/lib or $prefix/libexec. That's just another solution to the same
> > problem.
>
> Though I worry I'll bring chaos, ...
>
> I had been kept another idea in my mind:  All daemons and/or utility
> commands would be subcommands of single program, similarly as
> subversion, openssl or git.
>
> man -s 1 sympa-close_list -> sympa close_list ... (currently sympa.pl 
> --close_list)
> man -s 8 sympa-bulk       -> bulk daemon          (currently bulk.pl)
That's not a reasonable choice for me.

The 'single binary, multiple subcommand' model isn't really clearer for 
end users, and make implementation slightly more complex. Basically, 
it's a loss for no gain.
--
Guillaume Rousse
INRIA, Direction des systèmes d'information
Domaine de Voluceau
Rocquencourt - BP 105
78153 Le Chesnay
Tel: 01 39 63 58 31

Attachment: smime.p7s
Description: Signature cryptographique S/MIME