Agreeing on some "rules" for packaging.

Agreeing on some "rules" for packaging.

[Cyril Roelandt]

Hey!

At the GHM, a Fedora hacker (whose name I forgot) suggested that it 
might be time for us to write down some "rules" as to how packaging 
should be done.

For instance, Andreas suggested that patches should only be used if we 
think they might be applied upstream, thus keeping the patches/ 
directory as small as possible; modifications specific to Guix should be 
written in Scheme.

I would also like to define a standard way to order the "#:use-module" 
at the beginning of each file, and agree on other "cosmetic" rules.

What do you think ?

Cyril.

Re: Agreeing on some "rules" for packaging.

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 819 bytes --]

> At the GHM, a Fedora hacker (whose name I forgot) suggested that it
> might be time for us to write down some "rules" as to how packaging
> should be done.

Do they have such rules?

> For instance, Andreas suggested that patches should only be used if we
> think they might be applied upstream, thus keeping the patches/
> directory as small as possible; modifications specific to Guix should
> be written in Scheme.

I agree.

> I would also like to define a standard way to order the "#:use-module"
> at the beginning of each file, and agree on other "cosmetic" rules.

I don’t think that the order is very important.  Sometimes I order them
alphabetically or based on the use of the functions, or group the
related ones.  Would you like to propose a similar set of rules for the
DSL itself?

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

Re: Agreeing on some "rules" for packaging.

[Andreas Enge]

Am Dienstag, 27. August 2013 schrieb Cyril Roelandt:
> At the GHM, a Fedora hacker (whose name I forgot) suggested that it
> might be time for us to write down some "rules" as to how packaging
> should be done.

It was Patrice Dumas. I agree and volunteer to propose such a document with 
good packaging practices.

I would also like to include a page on python with a naming scheme 
suggestion. Would you mind holding back on python3 for so long? At least 
the python part should be ready by tomorrow evening.

Andreas

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Cyril Roelandt <tipecaml@gmail.com> skribis:

> At the GHM, a Fedora hacker (whose name I forgot) suggested that it
> might be time for us to write down some "rules" as to how packaging
> should be done.

Sounds like a good idea.  In general, when working in a group, I think
it’s better to discuss what our expectations are, and write as much of
it down, to avoid any misunderstandings or frustration.  So yes, let’s
do it.

> For instance, Andreas suggested that patches should only be used if we
> think they might be applied upstream, thus keeping the patches/
> directory as small as possible;

Agreed.  Also, patches should start with a comment saying what they do,
and possibly what their upstream status is (submitted, will never be
submitted because it’s Guix-specific, etc.); perhaps the format of that
comment could even be formalized.

> modifications specific to Guix should be written in Scheme.

Sometimes that may be hard or inconvenient though, so I would not set
that in stone.

> I would also like to define a standard way to order the "#:use-module"
> at the beginning of each file, and agree on other "cosmetic" rules.

Not convinced about the ordering.  ;-)

> What do you think ?

These are good examples of the kind of rules we may want to discuss and
adopt.

What about discussing them as patches for the “Packaging Guidelines”
section of the manual, for example?  (With one thread per suggestion.)

Thanks!

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Cyril Roelandt]

On 08/28/2013 02:51 PM, Ludovic Courtès wrote:
> Cyril Roelandt <tipecaml@gmail.com> skribis:
>
>> At the GHM, a Fedora hacker (whose name I forgot) suggested that it
>> might be time for us to write down some "rules" as to how packaging
>> should be done.
>
> Sounds like a good idea.  In general, when working in a group, I think
> it’s better to discuss what our expectations are, and write as much of
> it down, to avoid any misunderstandings or frustration.  So yes, let’s
> do it.
>
>> For instance, Andreas suggested that patches should only be used if we
>> think they might be applied upstream, thus keeping the patches/
>> directory as small as possible;
>
> Agreed.  Also, patches should start with a comment saying what they do,
> and possibly what their upstream status is (submitted, will never be
> submitted because it’s Guix-specific, etc.); perhaps the format of that
> comment could even be formalized.
>
>> modifications specific to Guix should be written in Scheme.
>
> Sometimes that may be hard or inconvenient though, so I would not set
> that in stone.
>

Yes, I wrote a patch that just added "#if 0 ... #endif" around a test, 
and that'd be harder to do in Scheme.

>> I would also like to define a standard way to order the "#:use-module"
>> at the beginning of each file, and agree on other "cosmetic" rules.
>
> Not convinced about the ordering.  ;-)
>

Isn't there such a convention in Scheme ? I'm often confused when 
looking at the beginning of a Scheme file. NetBSD has such rules for its 
includes 
(http://cvsweb.netbsd.org/bsdweb.cgi/src/share/misc/style?rev=HEAD&content-type=text/x-cvsweb-markup).

>> What do you think ?
>
> These are good examples of the kind of rules we may want to discuss and
> adopt.


I'm also wondering how to name python packages. foo ? python-foo and 
python3-foo ? python2-foo and python-foo ?


Cyril.

Re: Agreeing on some "rules" for packaging.

[Andreas Enge]

[-- Attachment #1: Type: text/plain, Size: 199 bytes --]

Please find attached a patch with proposed conventions for package names,
including in the presence of packages for several version numbers
(such as python itself), and for python modules.

Andreas


[-- Attachment #2: 0001-doc-Add-package-guidelines-for-names-and-numbers.patch --]
[-- Type: text/x-diff, Size: 3935 bytes --]

From ee85f3dbe9ec38abffd08971be27b876634392ee Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas@enge.fr>
Date: Wed, 28 Aug 2013 22:51:20 +0200
Subject: [PATCH] doc: Add package guidelines for names and numbers.

* doc/guix.texi: Three new subsections.
---
 doc/guix.texi |   82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index dfffdbf..ca2871b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1631,7 +1631,10 @@ needed is to review and apply the patch.
 
 
 @menu
-* Software Freedom::                         What may go into the distribution.
+* Software Freedom::     What may go into the distribution.
+* Package Naming::       What's in a name?
+* Version Numbers::      When the name is not enough.
+* Python Modules::       Taming the snake.
 @end menu
 
 @node Software Freedom
@@ -1654,6 +1657,83 @@ reject non-free firmware, recommendations of non-free software, and
 discuss ways to deal with trademarks and patents.
 
 
+@node Package Naming
+@subsection Package Naming
+
+A package has actually two names associated to it:
+First, there is the name of the @emph{Scheme variable}, the one following
+@code{define-public}. By this name, the package can be made known in the
+Scheme code, for instance as input to another package.
+Second, there is the string in the @code{name} field of a package definition.
+This name is used by the package manager.
+
+Both are usually the same and correspond to the lowercase conversion of the
+project name chosen by upstream. For instance, the GNUnet project is packaged
+as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
+unless these are already part of the official project name.
+But see @ref{Python Modules} for special rules concerning modules for
+the Python language.
+
+
+@node Version Numbers
+@subsection Version Numbers
+
+We usually package only the latest version of a given free software
+project. But sometimes, for instance for incompatible library versions,
+two (or more) versions of the same package are needed. These require different
+Scheme variable names. We use the name as defined in @ref {Package Naming}
+for the most recent version; previous versions use the same name, suffixed
+by @code{-} and the smallest prefix of the version number that may
+distinguish the two versions.
+
+The name inside the package definition is the same for all versions of a
+package and does not contain any version number.
+
+For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
+@example
+(define-public gtk+
+  (package
+   (name "gtk+")
+   (version "3.9.12")
+   ...))
+(define-public gtk+-2
+  (package
+   (name "gtk+")
+   (version "2.24.20")
+   ...))
+@end example
+If we also wanted GTK+ 3.8.2, this would be packaged as
+@example
+(define-public gtk+-3.8
+  (package
+   (name "gtk+")
+   (version "3.8.2")
+   ...))
+@end example
+
+
+@node Python Modules
+@subsection Python Modules
+
+We currently package Python 2 and Python 3, under the Scheme variable names
+@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
+To avoid confusion and naming clashes with other programming languages, it
+seems desirable that the name of a package for a Python module contains
+the word @code{python}.
+Some modules are compatible with only one version of Python, others with both.
+If the package Foo compiles only with Python 3, we name it
+@code{python-foo}; if it compiles only with Python 2, we name it
+@code{python2-foo}. If it is compatible with both versions, we create two
+packages with the corresponding names.
+
+If a project already contains the word @code{python}, we drop this;
+for instance, the module python-dateutil is packaged under the names
+@code{python-dateutil} and @code{python2-dateutil}.
+
+
+
+
+
 @node Bootstrapping
 @section Bootstrapping
 
-- 
1.7.10.4

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Cyril Roelandt <tipecaml@gmail.com> skribis:

> On 08/28/2013 02:51 PM, Ludovic Courtès wrote:
>> Cyril Roelandt <tipecaml@gmail.com> skribis:

[...]

>>> I would also like to define a standard way to order the "#:use-module"
>>> at the beginning of each file, and agree on other "cosmetic" rules.
>>
>> Not convinced about the ordering.  ;-)
>>
>
> Isn't there such a convention in Scheme ?

Not that I know of.

I generally put the (guix ...) modules first, and the (gnu ...) second,
I think.  IOW, the “foundational” first.

>> These are good examples of the kind of rules we may want to discuss and
>> adopt.
>
>
> I'm also wondering how to name python packages. foo ? python-foo and
> python3-foo ? python2-foo and python-foo ?

Presumably pythonX-foo.  Andreas?

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Cyril Roelandt]

On 08/29/2013 12:42 AM, Ludovic Courtès wrote:
> Also, please leave two spaces after an end-of-sentence period.

Do you have a link to an explanation of this rule ?

Cyril.

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> Please find attached a patch with proposed conventions for package names,
> including in the presence of packages for several version numbers
> (such as python itself), and for python modules.

Looks like it already went in.  :-)

That seems like a very good start.  I agree with the proposed rules,
so I just have a cosmetic comments:

> diff --git a/doc/guix.texi b/doc/guix.texi
> index dfffdbf..ca2871b 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -1631,7 +1631,10 @@ needed is to review and apply the patch.
>  
>  
>  @menu
> -* Software Freedom::                         What may go into the distribution.
> +* Software Freedom::     What may go into the distribution.
> +* Package Naming::       What's in a name?
> +* Version Numbers::      When the name is not enough.
> +* Python Modules::       Taming the snake.
>  @end menu

I would perhaps move “Python Modules” into a “Specific Packages”
subsection (or something like that), where we might eventually have
“Perl Packages” as well.  WDYT?

> +@node Package Naming
> +@subsection Package Naming
> +
> +A package has actually two names associated to it:

s/to it/with it/

> +First, there is the name of the @emph{Scheme variable}, the one following
> +@code{define-public}. By this name, the package can be made known in the
> +Scheme code, for instance as input to another package.
> +Second, there is the string in the @code{name} field of a package definition.
> +This name is used by the package manager.

s/package manager/commands such as @command{guix package} and @command{guix build}/

> +Both are usually the same and correspond to the lowercase conversion of the
> +project name chosen by upstream. For instance, the GNUnet project is packaged

s/by upstream/upstream/

> +as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
> +unless these are already part of the official project name.
> +But see @ref{Python Modules} for special rules concerning modules for

s/But see @ref{Python Modules}/@xref{Python Modules},/

(info "(texinfo) @xref")

> +@node Version Numbers
> +@subsection Version Numbers
> +
> +We usually package only the latest version of a given free software
> +project. But sometimes, for instance for incompatible library versions,
> +two (or more) versions of the same package are needed. These require different
> +Scheme variable names. We use the name as defined in @ref {Package Naming}

s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/

> +for the most recent version; previous versions use the same name, suffixed
> +by @code{-} and the smallest prefix of the version number that may
> +distinguish the two versions.
> +
> +The name inside the package definition is the same for all versions of a
> +package and does not contain any version number.
> +
> +For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
> +@example
> +(define-public gtk+
> +  (package
> +   (name "gtk+")
> +   (version "3.9.12")
> +   ...))
> +(define-public gtk+-2
> +  (package
> +   (name "gtk+")
> +   (version "2.24.20")
> +   ...))
> +@end example
> +If we also wanted GTK+ 3.8.2, this would be packaged as
> +@example
> +(define-public gtk+-3.8
> +  (package
> +   (name "gtk+")
> +   (version "3.8.2")
> +   ...))
> +@end example

Add linebreaks around @example, possibly with @noindent before the
lonely lines.

> +@node Python Modules
> +@subsection Python Modules
> +
> +We currently package Python 2 and Python 3, under the Scheme variable names
> +@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
> +To avoid confusion and naming clashes with other programming languages, it
> +seems desirable that the name of a package for a Python module contains
> +the word @code{python}.
> +Some modules are compatible with only one version of Python, others with both.

Add linebreak before “Some modules”.

Also, please leave two spaces after an end-of-sentence period.

Thanks,
Ludo’.

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Cyril Roelandt <tipecaml@gmail.com> skribis:

> On 08/29/2013 12:42 AM, Ludovic Courtès wrote:
>> Also, please leave two spaces after an end-of-sentence period.
>
> Do you have a link to an explanation of this rule ?

From (info "(texinfo) Not Ending a Sentence"):

  Depending on whether a period or exclamation point or question mark is
  inside or at the end of a sentence, slightly less or more space is
  inserted after a period in a typeset manual.  Since it is not always
  possible to determine automatically when a period ends a sentence,
  special commands are needed in some circumstances.  Usually, Texinfo can
  guess how to handle periods, so you do not need to use the special
  commands; you just enter a period as you would if you were using a
  typewriter: put two spaces after the period, question mark, or
  exclamation mark that ends a sentence.

IOW, the intent is to (1) mimic typographical rules, where an
end-of-sentence space is slightly wider than (say) an
after-abbreviation-period space, and (2) to guide TeX(info).  Also, the
‘forward-sentence’ (M-e) command in Emacs expects that.

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 575 bytes --]

While we are at it, we could agree on quotation marks.  I know that it
sounds like bikeshedding…  However, it doesn’t look right when some
people use `' and others use ''.

“Although GNU programs traditionally used 0x60 (‘`’) for opening and 0x27
(‘'’) for closing quotes, nowadays quotes ‘`like this'’ are typically
rendered asymmetrically, so quoting ‘"like this"’ or ‘'like this'’
typically looks better.” [1]

I’d prefer '' but will use `' if we agree on that.

[1] https://gnu.org/prep/standards/standards.html#Quote-Characters

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

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> While we are at it, we could agree on quotation marks.  I know that it
> sounds like bikeshedding…  However, it doesn’t look right when some
> people use `' and others use ''.
>
> “Although GNU programs traditionally used 0x60 (‘`’) for opening and 0x27
> (‘'’) for closing quotes, nowadays quotes ‘`like this'’ are typically
> rendered asymmetrically, so quoting ‘"like this"’ or ‘'like this'’
> typically looks better.” [1]
>
> I’d prefer '' but will use `' if we agree on that.
>
> [1] https://gnu.org/prep/standards/standards.html#Quote-Characters

Yes, that change in the GCS is recent, and I haven’t completely changed
my habits.

IMO the rule should be: use Unicode quotation marks wherever possible
(almost everywhere), use what Texinfo prescribes in Texinfo (that is,
like `this' and ``that''), and use what the GCS says elsewhere.

I tend to use ASCII quotation marks in source files; the main reason for
that is that typopunct-mode in Scheme files would be annoying (if you
know of other ways do use Unicode quotation marks in Emacs, lemme know.)

Thoughts?

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 700 bytes --]

> Yes, that change in the GCS is recent, and I haven’t completely changed
> my habits.

> IMO the rule should be: use Unicode quotation marks wherever possible
> (almost everywhere), use what Texinfo prescribes in Texinfo (that is,
> like `this' and ``that''), and use what the GCS says elsewhere.

> I tend to use ASCII quotation marks in source files; the main reason for
> that is that typopunct-mode in Scheme files would be annoying (if you
> know of other ways do use Unicode quotation marks in Emacs, lemme know.)

> Thoughts?

OK, but the above doesn’t answer my question.  Which quotation marks
should be used in source files: `' or ''?

And what about commit messages?

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

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> Yes, that change in the GCS is recent, and I haven’t completely changed
>> my habits.
>
>> IMO the rule should be: use Unicode quotation marks wherever possible
>> (almost everywhere), use what Texinfo prescribes in Texinfo (that is,
>> like `this' and ``that''), and use what the GCS says elsewhere.
>
>> I tend to use ASCII quotation marks in source files; the main reason for
>> that is that typopunct-mode in Scheme files would be annoying (if you
>> know of other ways do use Unicode quotation marks in Emacs, lemme know.)
>
>> Thoughts?
>
> OK, but the above doesn’t answer my question.  Which quotation marks
> should be used in source files: `' or ''?

Unicode if that’s convenient, or 'this'.  (Although again, I tend to
do `this'...)

> And what about commit messages?

Ditto.

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

While we’re at discussing rules: commit e1c5a83 adds a “Coding Style”
section in ‘HACKING’, with the ideas that came to mind.

Let me know what you think.

Ludo’.

Re: Agreeing on some "rules" for packaging.

[Andreas Enge]

On Thu, Aug 29, 2013 at 12:42:31AM +0200, Ludovic Courtès wrote:
> Looks like it already went in.  :-)

Yes, that was a random push, sorry! But the good thing in a vcs is that one
can always modify and go back.

> I would perhaps move “Python Modules” into a “Specific Packages”
> subsection (or something like that), where we might eventually have
> “Perl Packages” as well.  WDYT?

Maybe once we have Perl Packages. I do not want to create too many sublevels.
Or we just create a separate section Perl Packages, depending on whether we
write essentially the same thing or not.

> > +A package has actually two names associated to it:
> s/to it/with it/

Ok.

> s/package manager/commands such as @command{guix package} and @command{guix build}/
"package management commands such as ... 

> > +Both are usually the same and correspond to the lowercase conversion of the
> > +project name chosen by upstream. For instance, the GNUnet project is packaged
> s/by upstream/upstream/

Ok.

> s/But see @ref{Python Modules}/@xref{Python Modules},/

No, since @xref creates text starting by "See", so is only suitable for the
beginning of a sentence. (But the info rendering is different from the pdf,
with which I am working mainly.)

> s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/

This also gives strange output with an additional "see".

> Add linebreaks around @example, possibly with @noindent before the
> lonely lines.

Okay for the line break (which does not change anything in pdf).

> Add linebreak before “Some modules”.

Okay.

> Also, please leave two spaces after an end-of-sentence period.

Okay. I suppose this also means that the period at the end of a sentence
is not allowed to fall at the end of an input line? So
"The weather is nice.
It is raining."

needs to become, for instance:
"The weather is
nice.  It is raining."?

Since there have not been any objections on the content of the guidelines,
maybe you could push Python 3 following this rule, Cyril? I am curious
whether all our packages will survive the switch to Python 3...

Andreas

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> On Thu, Aug 29, 2013 at 12:42:31AM +0200, Ludovic Courtès wrote:

[...]

>> I would perhaps move “Python Modules” into a “Specific Packages”
>> subsection (or something like that), where we might eventually have
>> “Perl Packages” as well.  WDYT?
>
> Maybe once we have Perl Packages. I do not want to create too many sublevels.
> Or we just create a separate section Perl Packages, depending on whether we
> write essentially the same thing or not.

OK, makes sense.

>> s/But see @ref{Python Modules}/@xref{Python Modules},/
>
> No, since @xref creates text starting by "See", so is only suitable for the
> beginning of a sentence.

What I’m suggesting here is precisely to start the sentence with @xref,
as recommended (info "(texinfo) @ref"):

    The '@ref' command can tempt writers to express themselves in a manner
  that is suitable for a printed manual but looks awkward in the Info
  format. [...]

    In general, it is best to use '@ref' only when you need some word
  other than "see" to precede the reference.  When "see" (or "See") is ok,
  '@xref' and '@pxref' are preferable.


>> s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/
>
> This also gives strange output with an additional "see".

It yields something like:

  previously defined (see Section 4.2 “Package Naming”)

How strange is that?  :-)

>> Also, please leave two spaces after an end-of-sentence period.
>
> Okay. I suppose this also means that the period at the end of a sentence
> is not allowed to fall at the end of an input line?

No, that’s not necessary, fortunately.

> Since there have not been any objections on the content of the guidelines,
> maybe you could push Python 3 following this rule, Cyril? I am curious
> whether all our packages will survive the switch to Python 3...

Well let’s pull the trigger and see what happens.  :-)

Thanks,
Ludo’.

Re: Agreeing on some "rules" for packaging.

[Andreas Enge]

On Sat, Aug 31, 2013 at 11:31:08AM +0200, Ludovic Courtès wrote:
> > No, since @xref creates text starting by "See", so is only suitable for the
> > beginning of a sentence.
>     In general, it is best to use '@ref' only when you need some word
>   other than "see" to precede the reference.  When "see" (or "See") is ok,
>   '@xref' and '@pxref' are preferable.

Well, but I would like to start my sentence with "But" and not "See", since
I am pointing the reader to something that contradicts the previous sentence...

> >> s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/
> > This also gives strange output with an additional "see".
>   previously defined (see Section 4.2 “Package Naming”)

and I would like to write "defined in Section..." and not "previously defined
(see Section".

These info rules should not meddle with our writing style. The result is what
I wanted to achieve in the pdf, and I think it looks acceptable in info.

> > Okay. I suppose this also means that the period at the end of a sentence
> > is not allowed to fall at the end of an input line?
> No, that’s not necessary, fortunately.

So texinfo interprets periods at the end of a line as ends of sentences?
And instead of
"a Scheme interpreter, e.g.
Guile"
one has to write
"a Scheme interpreter,
e.g. Guile"?

Andreas

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Andreas Enge <andreas@enge.fr> skribis:

> On Sat, Aug 31, 2013 at 11:31:08AM +0200, Ludovic Courtès wrote:
>> > No, since @xref creates text starting by "See", so is only suitable for the
>> > beginning of a sentence.
>>     In general, it is best to use '@ref' only when you need some word
>>   other than "see" to precede the reference.  When "see" (or "See") is ok,
>>   '@xref' and '@pxref' are preferable.
>
> Well, but I would like to start my sentence with "But" and not "See", since
> I am pointing the reader to something that contradicts the previous sentence...
>
>> >> s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/
>> > This also gives strange output with an additional "see".
>>   previously defined (see Section 4.2 “Package Naming”)
>
> and I would like to write "defined in Section..." and not "previously defined
> (see Section".
>
> These info rules should not meddle with our writing style.

Sure, but the topic of making cross-references that work across media
isn’t trivial, which is why Texinfo has several commands with clear
rules.

> The result is what I wanted to achieve in the pdf, and I think it
> looks acceptable in info.

Well, by definition, constructs like these look bad in Info.  However,
perhaps it’s kinda OK with Emacs’ Info reader, which uses hyperlinks.

Nevertheless, I’ve never found it such a hindrance to follow the Texinfo
rules.

>> > Okay. I suppose this also means that the period at the end of a sentence
>> > is not allowed to fall at the end of an input line?
>> No, that’s not necessary, fortunately.
>
> So texinfo interprets periods at the end of a line as ends of sentences?

Presumably, but I don’t know the details.

Thanks,
Ludo’.

Re: Agreeing on some "rules" for packaging.

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 449 bytes --]

I’ve just fixed a small bug [1].  Maybe we should agree to run

make distclean && ./boostrap && ./configure && make && make check

before pushing, or will it be too tedious?

Also, I don’t like the ‘license:’ prefix.  What about something like
‘l:’?  It’ll probably be even better to use ‘#:select’ when it’s
possible.

[1] http://git.savannah.gnu.org/cgit/guix.git/commit/?id=a129e0d877f125693f58457d55973d184468b461

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

Re: Agreeing on some "rules" for packaging.

[Andreas Enge]

On Sat, Sep 07, 2013 at 12:20:23PM +0400, Nikita Karetnikov wrote:
> make distclean && ./boostrap && ./configure && make && make check
> before pushing, or will it be too tedious?

Would "make" not be enough? Usually there is a warning message when there
is a problem.

> Also, I don’t like the ‘license:’ prefix.  What about something like
> ‘l:’?  It’ll probably be even better to use ‘#:select’ when it’s
> possible.

Personally, I would do things the other way round and always use a prefix...
Then I can simply write down the license of a package without checking
whether it is already selected in the module.

Andreas

Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> I’ve just fixed a small bug [1].  Maybe we should agree to run
>
> make distclean && ./boostrap && ./configure && make && make check
>
> before pushing, or will it be too tedious?

For this kind of error (unbound variable), just typing ‘make’ or C-c C-k
in Geiser reports the unbound variable.

Doing that before pushing is definitely advised.

Sometimes that’s not enough to detect other errors (such as circular
dependencies), but that’s quite unusual.

> Also, I don’t like the ‘license:’ prefix.  What about something like
> ‘l:’?  It’ll probably be even better to use ‘#:select’ when it’s
> possible.

Yes, I prefer #:select when possible, but otherwise either of these two
prefixes is fine with me.

Thanks,
Ludo’.