[PATCH] doc: Add 'copyrights' and 'license' macros.

[PATCH] doc: Add 'copyrights' and 'license' macros.

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 249 bytes --]

What do you think about this change?  I used ‘itemize’ to avoid
extraneous blank lines.  The only downside is that the indentation of
the ‘copyrights’ macro slightly differs from the surrounding text.

Karl, do you know a better way?


[-- Attachment #1.2: 0001-doc-Add-copyrights-and-license-macros.patch --]
[-- Type: text/x-diff, Size: 2889 bytes --]

From b8867a4956af60065200c3b89604108cd7e46e83 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Wed, 9 Oct 2013 10:37:34 +0000
Subject: [PATCH] doc: Add 'copyrights' and 'license' macros.

* doc/guix.texi (YEARS): Remove it.
  (copyrights, license): Add these macros and use them.
---
 doc/guix.texi |   39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index ceb8046..7408be0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8,7 +8,6 @@
 @c %**end of header
 
 @include version.texi
-@set YEARS 2012, 2013
 
 @dircategory Package management
 @direntry
@@ -31,16 +30,28 @@
 Edition @value{EDITION} @*
 @value{UPDATED} @*
 
-Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov
+@macro copyrights
+@itemize @w{}
+@item Copyright @copyright{} 2012, 2013 Ludovic Court@`es
+@item Copyright @copyright{} 2013 Andreas Enge
+@item Copyright @copyright{} 2013 Nikita Karetnikov
+@end itemize
+@end macro
 
-@ifinfo
-@quotation
+@macro license
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+Documentation License.''
+@end macro
+
+@copyrights
+
+@ifinfo
+@quotation
+@license
 @end quotation
 @end ifinfo
 
@@ -49,14 +60,9 @@ Documentation License''.
 @copying
 This manual documents GNU Guix version @value{VERSION}.
 
-Copyright @copyright{} @value{YEARS} Ludovic Courtès
+@copyrights
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License.''
+@license
 @end copying
 
 @contents
@@ -70,14 +76,9 @@ package management tool written for the GNU system.
 
 
 @quotation
-Copyright @copyright{} @value{YEARS} Ludovic Courtès, Andreas Enge, Nikita Karetnikov
+@copyrights
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License.''
+@license
 @end quotation
 
 @menu
-- 
1.7.9.5


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [PATCH] doc: Add 'copyrights' and 'license' macros.

[Karl Berry]

    What do you think about this change?  

Sorry, I don't understand what problem you're trying to solve.
Why are you separating copyright text and license text?  
Can you send me the whole file (beginning of it, anyway)?
The diff is hard to read.

As for the @itemize of names, I would suggest explicit line breaks
instead, to avoid unnecessary spacing.
Copyright ... name1@*
Copyright ... name2@*
Copyright ... name3

Best,
karl

Re: [PATCH] doc: Add 'copyrights' and 'license' macros.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> From b8867a4956af60065200c3b89604108cd7e46e83 Mon Sep 17 00:00:00 2001
> From: Nikita Karetnikov <nikita@karetnikov.org>
> Date: Wed, 9 Oct 2013 10:37:34 +0000
> Subject: [PATCH] doc: Add 'copyrights' and 'license' macros.
>
> * doc/guix.texi (YEARS): Remove it.
>   (copyrights, license): Add these macros and use them.

Fine with me if it uses explicit line breaks as Karl suggested instead
of @itemize.

And yeah, there could be a single macro since the two always go
together.

Ludo’.

Re: [PATCH] doc: Add 'copyrights' and 'license' macros.

[Karl Berry]

    And yeah, there could be a single macro since the two always go
    together.

Why is a macro needed at all?
(vs. just using text inside @copying).

Re: [PATCH] doc: Add 'copyrights' and 'license' macros.

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 825 bytes --]

>>> Sorry, I don't understand what problem you're trying to solve.
>>> Why are you separating copyright text and license text?  

I don’t know how to keep the @ifinfo trick (see the attachment) without
separating them.  Maybe the @ifinfo part should be removed.

>>> Can you send me the whole file (beginning of it, anyway)?
>>> The diff is hard to read.

Attached.

>> And yeah, there could be a single macro since the two always go
>> together.

> Why is a macro needed at all?
> (vs. just using text inside @copying).

In the document, nearly the same (more on that later) copyright notice
is repeated three times.  A new contributor would have to adjust each
notice, which is error-prone.

Now, I said “nearly” because the “Copyright” lines are different, but
they should be identical.


[-- Attachment #1.2: guix.texi.beginning --]
[-- Type: text/plain, Size: 2585 bytes --]

\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@settitle GNU Guix Reference Manual
@c %**end of header

@include version.texi
@set YEARS 2012, 2013

@dircategory Package management
@direntry
* guix: (guix).       Guix, the functional package manager.
* guix package: (guix)Invoking guix package
                      Managing packages with Guix.
* guix build: (guix)Invoking guix build
                      Building packages with Guix.
@end direntry

@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author Ludovic Courtès
@author Andreas Enge
@author Nikita Karetnikov

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov

@ifinfo
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end ifinfo

@end titlepage

@copying
This manual documents GNU Guix version @value{VERSION}.

Copyright @copyright{} @value{YEARS} Ludovic Courtès

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying

@contents

@c *********************************************************************
@node Top
@top GNU Guix

This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.


@quotation
Copyright @copyright{} @value{YEARS} Ludovic Courtès, Andreas Enge, Nikita Karetnikov

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [PATCH] doc: Add 'copyrights' and 'license' macros.

[Karl Berry]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3399 bytes --]

    I donœôòùt know how to keep the @ifinfo trick

I see no need for @ifinfo.  It has no effect inside @titlepage anyway,
since @titlepage ... @end titlepage is ignored for Info output.

    nearly the same (more on that later) copyright notice
    is repeated three times.

1) @copying should come first.

2) @insertcopying can/should be used to insert the copying text in
@titlepage and anywhere else.  I created @insertcopying at the same time
as @copying, precisely to avoid having to write the copying text more
than once.

3) I see no need for @macro.  I also don't think a YEARS variable makes
sense.  The years will be different for different people.

4) I see no need for a separate EDITION and UPDATED in the
@titlepage text, but whatever.

5) The period outside the quotes in the standard text is intentional
(per fdl.texi).  Not that it's the end of the world to have it inside.

6) All this is shown in the "short example" document that is in the
Texinfo manual.  

Appended is another version of your frontmatter this way.  (Probably
with the accented characters messed up, but you get the idea.)

BTW, rms prefers that the Top node not include @insertcopying, but it's
up to you.  (I see I haven't taken @insertcopying out of the Top node
in the Texinfo manual's example document.  Oops.)

BTW 2, the spaces in your "guix package" and "guix build" dir entries 
make completion painful.  Also you're missing periods after the node
names.  Also the dir file is much more readable if entries are kept on
one line at all costs.  I suggest:
@direntry
* Guix (guix).                      Guix, the functional package manager.
* guix-package (guix)Invoking guix package.  Managing packages with Guix.
* guix-build (guix)Invoking guix build.      Building packages with Guix.
@end direntry

Ok, that's more than enough for one message ...

Best,
karl


\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@settitle GNU Guix Reference Manual
@c %**end of header

@include version.texi
@set YEARS 2012, 2013

@copying
This manual documents GNU Guix version @value{VERSION}.

Copyright @copyright{} @value{YEARS} Ludovic Courtès

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying

@dircategory Package management
@direntry
* guix: (guix).       Guix, the functional package manager.
* guix package: (guix)Invoking guix package
                      Managing packages with Guix.
* guix build: (guix)Invoking guix build
                      Building packages with Guix.
@end direntry

@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author Ludovic Courtès
@author Andreas Enge
@author Nikita Karetnikov

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top GNU Guix

This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.

@insertcopying

[PATCH] doc: Improve the copyright notice.

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 79 bytes --]

Karl, thank you so much.  I hope it’s OK now.

Ludo, what do you think?


[-- Attachment #1.2: 0001-doc-Improve-the-copyright-notice.patch --]
[-- Type: text/x-diff, Size: 3488 bytes --]

From a384d93077e1dab066e0761a056b52fe1ba6dfd6 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Fri, 11 Oct 2013 15:52:27 +0000
Subject: [PATCH] doc: Improve the copyright notice.

---
 doc/guix.texi |   55 +++++++++++++++----------------------------------------
 1 file changed, 15 insertions(+), 40 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index ceb8046..a78000f 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8,7 +8,19 @@
 @c %**end of header
 
 @include version.texi
-@set YEARS 2012, 2013
+
+@copying
+Copyright @copyright{} 2012, 2013 Ludovic Court@`es@*
+Copyright @copyright{} 2013 Andreas Enge@*
+Copyright @copyright{} 2013 Nikita Karetnikov
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@end copying
 
 @dircategory Package management
 @direntry
@@ -22,7 +34,7 @@
 @titlepage
 @title GNU Guix Reference Manual
 @subtitle Using the GNU Guix Functional Package Manager
-@author Ludovic Courtès
+@author Ludovic Court@`es
 @author Andreas Enge
 @author Nikita Karetnikov
 
@@ -31,34 +43,9 @@
 Edition @value{EDITION} @*
 @value{UPDATED} @*
 
-Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov
-
-@ifinfo
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
-@end quotation
-@end ifinfo
-
+@insertcopying
 @end titlepage
 
-@copying
-This manual documents GNU Guix version @value{VERSION}.
-
-Copyright @copyright{} @value{YEARS} Ludovic Courtès
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License.''
-@end copying
-
 @contents
 
 @c *********************************************************************
@@ -68,18 +55,6 @@ Documentation License.''
 This document describes GNU Guix version @value{VERSION}, a functional
 package management tool written for the GNU system.
 
-
-@quotation
-Copyright @copyright{} @value{YEARS} Ludovic Courtès, Andreas Enge, Nikita Karetnikov
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License.''
-@end quotation
-
 @menu
 * Introduction::                What is Guix about?
 * Installation::                Installing Guix.
-- 
1.7.9.5


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [PATCH] doc: Improve the copyright notice.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> Karl, thank you so much.  I hope it’s OK now.
>
> Ludo, what do you think?

Fine with me, but make sure the copyright notice still shows up in Info,
HTML, and PS/PDF (ISTR that it had to be repeated so that it would be
visible in Info and HTML.)

Ludo’.

Re: [PATCH] doc: Improve the copyright notice.

[Karl Berry]

    make sure the copyright notice still shows up in Info,
    HTML, and PS/PDF

It's always good to check, but like I said, that is exactly why I
invented @copying in the first place (back in 2002).  I wrote about it
in the Texinfo manual.

I think it was not working for you (if indeed it wasn't) because your
use of @copying was too late in the source file.

    visible in Info and HTML.)

It depends on what you mean by "visible".  The @copying on its own will
include the copying text as a comment in all the makeinfo output files
(Info, HTML, Docbook, XML).  That's how rms wanted it, and that's what
takes care of the legal necessities.

If you want casual readers of the manual to see the copying terms, as
well as people looking at the source, then you can use @insertcopying in
the Top node (as well as in the @titlepage, which is what takes care of
TeX).  Like I also said, rms prefers that not be done, but didn't feel
strongly enough to make it a GNU requirement either way, so it's up to you.

Best,
karl

Re: [PATCH] doc: Improve the copyright notice.

[Ludovic Courtès]

karl@freefriends.org (Karl Berry) skribis:

>     make sure the copyright notice still shows up in Info,
>     HTML, and PS/PDF
>
> It's always good to check, but like I said, that is exactly why I
> invented @copying in the first place (back in 2002).  I wrote about it
> in the Texinfo manual.
>
> I think it was not working for you (if indeed it wasn't) because your
> use of @copying was too late in the source file.

OK.

>     visible in Info and HTML.)
>
> It depends on what you mean by "visible".  The @copying on its own will
> include the copying text as a comment in all the makeinfo output files
> (Info, HTML, Docbook, XML).  That's how rms wanted it, and that's what
> takes care of the legal necessities.

By visible I meant that the copyright notice would appear in the Top
node in Info, and at the beginning of the HTML document (I see the
Coreutils and gawk manuals do that, but not the Texinfo and libc
manuals, for instance.)

I thought this was good practice, but I’m glad to hear it’s actually not
the recommended way to deal with it.

> If you want casual readers of the manual to see the copying terms, as
> well as people looking at the source, then you can use @insertcopying in
> the Top node (as well as in the @titlepage, which is what takes care of
> TeX).  Like I also said, rms prefers that not be done, but didn't feel
> strongly enough to make it a GNU requirement either way, so it's up to you.

OK, then I’m happy to follow the recommended approach.

So Nikita: please ignore what I wrote and follow Karl’s advice.  :-)

Thanks for taking the time to explain,
Ludo’.