Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 30/01/2014 07:45, IKEDA Soji a écrit :
> > 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
Sure, there is no mandatory requirement for a top-level man page, but I 
still think it would be useful. At least, for centralizing content which 
is uselessly duplicated in all other man pages, such as licensing and 
copyright informations. And for avoiding mixing project-level 
documentation and executable-specific documentation. If that's both 
useful, and technically simple, I don't see any reason to avoid it just 
because there is no clearly dedicated man page section...

Anyway, to make my point clear, I don't require a generic top-level 
'sympa-the-project' man page, but:
1) I'd prefer to avoid to mix 'sympa-the-binary' specific informations 
with 'sympa-the-project' generic informations, such as references to the 
bug tracker for instance.
2) I'd prefer to avoid duplicating in each man page the same licensing, 
copyright and authorship information
3) I'd prefer to avoid duplicating in each file the same copyright and 
licensing declaration twice, first as a file header (standard comment) 
and second as pod content (intended to be externalized as a man page)

All of this strictly for the sake of readability and maintainabily. As 
you said yourself in another thread, 'less information' is better as 
'untrustable information'. If you're OK on all of those points, I can 
perfectly live without such generic man page.

> We may not force completing everything in source distribution.
Sure. Let's drop legal stuff then, and focus on code :)

> (OTOH histories by each module would be kept as much as we can.)
Sure, as long as it doesn't imply cluttering each file content endlessly 
with unreliable cut'n'paste artefacts.

[..]
> > > 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).
You're mixing man page and executable granularity in your prosal.

Regarding executable granularity, I'm perfectly fine with splitting the 
various admin-related interactive usage of the current sympa.pl 
executable as subcommand of a single sympa_admin binary. I disagree, 
tough, with mixing interactive (admin duties) and non-interactive usages 
(daemon running) as subcommand of the same command.

ie, the following does not make sense:
sympa close-some-list for closing a list
sympa bulk            for launching the bulk daemon

Regarding man page granularity, I think it's just conveninet to use the 
same granularity.

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