Re: Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz <tjolitz@gmail.com>]

Richard Stallman <rms@gnu.org> writes:

>         [ To any NSA and FBI agents reading my email: please consider
>         [ whether defending the US Constitution against all enemies,
>         [ foreign or domestic, requires you to follow Snowden's example.
>
> Regarding the file keywords, the change you've proposed has some fatal
> flaws.
>
>   | ;; ** MetaData
>   | ;;   :PROPERTIES:
>   | ;;   :copyright: Thorsten_Jolitz
>   | ;;   :copyright-since: 2013
>   | ;;   :version:  0.9
>   | ;;   :licence:  GPL3+
>   | ;;   :licence-url: http://www.gnu.org/licenses/
>
> It is legally inadequate, since it doesn't have a standard copyright
> notice.  A standard copyright notice looks like
>
>     Copyright YEARS NAME
>
> It is inadequate for informing users about their rights, and the lack
> of warranty, and about our philosophy, because it lacks the explicit
> license notice which states those things.  It may also be legally
> insufficient for making the license clear.
>
> We want people to see these words in the source file:
>
>       | ;; This file is part of GNU Emacs.
>       |
>       | ;; GNU Emacs is free software: you can redistribute it and/or modify
>       | ;; it under the terms of the GNU General Public License as published by
>       | ;; the Free Software Foundation,  either version 3 of the License,  or
>       | ;; (at your option) any later version.
>       |
>       | ;; GNU Emacs is distributed in the hope that it will be useful,
>       | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
>       | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>       | ;; GNU General Public License for more details.
>       |
>       | ;; You should have received a copy of the GNU General Public License
>       | ;; along with GNU Emacs.  If not,  see <http://www.gnu.org/licenses/>.
>
> This part has to be kept as it is.
>
> Those issues don't apply to the library header lines:
>
>   | ;; Maintainer: FSF
>   | ;; Keywords: help,  internal
>   | ;; Package: emacs
>
> We could change them if it is an improvement.  However, I think your
> format is worse for humans.  We should not make it worse for humans
> just to cater to programs that some people use.  You can change the
> programs instead.

Indeed, until now I did not get much positive feedback about the looks
of these property drawers in Elisp libraries, not even from Org-mode
users - although they seem to be more suited for meta-data than just
free text from a conceptual point of view.

What would be really helpful, besides saner official recommendations for
file structuring, would be an up-to-date official template for this
meta-data section (maybe there is one out there but I missed it?).

(Private) tools could then convert this template into (e.g.) easy to
handle Org-mode syntax like above, and convert them back to more human
readable traditional syntax before a library is added to some repo.

-- 
cheers,
Thorsten