Andreas Enge <[email protected]> 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’.
