Re: Agreeing on some "rules" for packaging.

[Ludovic Courtès]

Andreas Enge <address@hidden> 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’.