Developers of Sympa

[IKEDA Soji <address@concealed>]

Hi Guillaume and all,

On Thu, 30 Jan 2014 15:58:54 +0100
Guillaume Rousse <address@concealed> wrote:

> 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 don't agree to several points.


Copyright notice and statement of permission in the head of each
file are recommended to apply the license (See GPL Howto).  These
should not be removed.

Guillaume seem to hesitate about following guideline or similar
things.
However, offensive words to guideline just because of it was not
made by himself are exactly nonproductive.

If he want to carry on his point, he may propose not to license
Sympa under GPL.
Or, he may start the new project not relying on GPL.

* Please note: In latter case, sources of Sympa cannot be used, if
  that project adopt license incompatible to GPL or public domain.
  The reason is simple: Sympa uses GPL.

Guillaume, please decide how to behave.  I won't write about this
issue anymore, and will observe what you do.


Besides on 2), it seems not neccessary that manual pages (not source
files) always contain copyright notice and/or statement about
licensing: In fact, for example, man pages of Perl don't do.  I
agree to him on this point.

On "authorship", it may be renovated to "HISTORY" section, as I
proposed.
Some contributors took part of multiple modules, however, such
fact does not mean that there are duplicated authorship (one reason
is that another contributor(s) can be added in the future).


I agree to Guillaume on the whole except the points I wrote.


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

I see.  How about this scheme?

sympa close_list <list>        : for closing a list, add subscribers etc.
sympa_util md5_encode_password : miscelaneous utilities (e.g. for upgrading)
sympa_daemon bulk start        : for starting, stopping etc. of daemon(s)

The last one (sympa_daemon) probably is not neccessary, though.


Regards,


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