Developers of Sympa

[Guillaume Rousse <address@concealed>]

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.

Another idea would however to rename sympa.pl to something else, for 
instance sympad.pl, once we extract the non-daemon part (something I'd 
like to do anyway for code readability), which would result in:
man sympa     -> sympa software global documentation
man sympad    -> sympad.pl executable specific documentation
man sympad.pl -> an alias for the last one

> Some notes (relatively unimportant):
>
> - I have another idea to rename "*.pl.in" to the name with single
>    extension such as "*.pin".  Suffix rule ".pin.pl:" will simplify
>    makefile more.
>    ".in" suffix is originally used by autotools.  We need not stick
>    to it.
No objection here.

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

> - [really unimportant] aliaswrapper, virtualwrapper and
>    alias_manager will be obsoleted.
That's important for me: the more code we can drop, the less code we 
have to reformat/cleanup/write test for. I'd be delighted to drop them :)

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