Developers of Sympa

[IKEDA Soji <address@concealed>]

Hi,

On Mon, 20 Jan 2014 15:03:32 +0100
Guillaume Rousse <address@concealed> wrote:

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

Once I thought similarly --- I told about Sympa.pod.

However, the issue which section is appropriate for "general
documentation" may not be solved anyway (by my thought above,
section is 3, 3pm or so).  Example of section 8 (polkit) is for
description on "framework" but not for things you presume.

In fact, documentation "on such as software's web site" I said
have already existed:
- Presentation
  http://www.sympa.org/manual/presentation
- Authors
  http://www.sympa.org/users/authors

We may not force completing everything in source distribution.
(OTOH histories by each module would be kept as much as we can.)

Sorry for my inconsistent arguement, but this is my thought for
the present.


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

No gain? At least such model will encourage modularization of current
sources, instead of single big set of miscelaneous functions
(especially of sympa.pl).

Anyway, this issue is not urgent.  I'll propose a concrete plan
before long.

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