Developers of Sympa

[IKEDA Soji <address@concealed>]

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.

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

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)

> > - [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 :)

Oh, I was too ahead.  alias_manager won't be obsoleted by now.
Other two will be obsoleted and sympa_newaliases will be added.


Regards,

--- Soji


> -- 
> Guillaume Rousse
> INRIA, Direction des systèmes d'information
> Domaine de Voluceau
> Rocquencourt - BP 105
> 78153 Le Chesnay
> Tel: 01 39 63 58 31
> 


-- 
株式会社 コンバージョン  セキュリティ&OSSソリューション部   池田荘児
〒231-0004　神奈川県横浜市中区元浜町3-21-2 ヘリオス関内ビル7F
e-mail address@concealed  TEL 045-640-3550
http://www.conversion.co.jp/