docs/66775: Clarification that port names should not contain version numbers

[Giorgos Keramidas]

On 2004-08-09 12:40, Peter Pentchev <roam at ringlet.net> wrote:
> On Sat, Jul 31, 2004 at 09:00:45PM +0000, Aasmund Eikli wrote:
> >
> >                       <para>Upgrade the copied port to the new version (remember
> >                         to change the <makevar>PORTNAME</makevar> so there
> >  -                     are not duplicate ports with the same name).</para>
> >  +                     are not duplicate ports with the same name).
> >  +                     Alternatively, change <makevar>LATEST_LINK</makevar>
> >  +                     depending on the purpose.</para>
> >                     </step>
>
> I think that 'remmeber to change the PORTNAME' and 'change LATEST_LINK'
> clauses should be at the same level of "nesting" [...]
> How about something like this instead?
>
> -		    <para>Upgrade the copied port to the new version (remember
> -		      to change the <makevar>PORTNAME</makevar> so there
> -		      are not duplicate ports with the same name).</para>
> +		    <para>Upgrade the copied port to the new version.  Remember
> +		      to change either the <makevar>PORTNAME</makevar> or
> +		      the <makevar>LATEST_LINK</makevar> variable so there
> +		      are not duplicate ports with the same name.</para>

Yep, this looks nice.  If Aasmund doesn't have any objections or did not
mean something different that I misunderstood, this is great.

> >               <literal>p5-Data-Dumper</literal>.  If the software in question
> >               has numbers, hyphens, or underscores in its name, you may include
> >  -           them as well (like <literal>kinput2</literal>).</para>
> >  +           them as well (like <literal>kinput2</literal>).
> >  +           Make sure that the <makevar>PORTNAME</makevar> variable and the
> >  +           <makevar>PORTVERSION</makevar> variable contains the name
>
> ITYM 'contain' here, since both variables form the sentence subject :)
>
> >  +           version number of the port respectively. You should not mix
> >  the two.</para>
>
> A minor point, but I've gathered the impression that two spaces are
> preferred before the start of a new sentence.  How about this?

Double vs. single space after punctuation is AFAIK a very common cause
of many a religious war and lots of flames.  "French spacing" with a
single space character is preferred by those who either live in French
speaking parts of the world or regularly use programs that are smart
enough to present nicely typeset and/or copies of the documents they
work on.

My preference is for double spaces between sentences, but it's not too
important; not important enough to force one of the two styles on
others, anyway.

In short, whatever suits your taste when you commit the text is fine but
it would also be awesome if we (all the committers that have access to
the doc/ tree) avoided committing stuff just to "fix" French spacing or
to revert previous "fixes".

>  	    <literal>Data::Dumper</literal> module becomes
>  	    <literal>p5-Data-Dumper</literal>.  If the software in question
>  	    has numbers, hyphens, or underscores in its name, you may include
> -	    them as well (like <literal>kinput2</literal>).</para>
> +	    them as well (like <literal>kinput2</literal>).  Make sure that
> +	    the <makevar>PORTNAME</makevar> and
> +	    <makevar>PORTVERSION</makevar> variables contain the name and
> +	    the version of the port respectively.  You should not mix the
> +	    two.</para>

This is great, IMHO.

> Thanks for your work on this :)

Indeed.  Thank you Aasmund!