PORTDOCS in the Porter's Handbook

[Yar Tikhiy]

On Sat, Jun 19, 2004 at 09:55:13PM +0400, Sergey Matveychuk wrote:
> Yar Tikhiy wrote:
> 
> >The neat PORTDOCS variable deserves more attention in
> >the Porter's Handbook, doesn't it?
> >
> >Hope I got it right...  Could anybody review the below
> >patch?  Thank you!
> 
> Don't forget to send-pr it.

Would you mind if, instead of filing a PR, I just commit the change
as soon as we reach a consensus over it? :-)

> Just one remark:
> 
> >+
> >+	<para>Recently a new feature was introduced to the ports framework
> >+	 in order to facilitate registering port documentation.  Instead of
> 
> I think the Porter's Handbook is not a diary and words like 'recently' 
> and 'a new feature' are not correct here. The text may be there for years.

Frankly, such a thought crossed my mind, too.  But in order to make
a statement that will stand for ages, we must decide here first what
is the status of the old and new ways for package listing doc files.
Possible choices include:

    a) either of them may be used at porter's option;
    b) the old way is documented so that the audience can see
       how legacy ports work, but porters are encouraged to use the
       new way, PORTDOCS, when creating or updating ports;
    c) ...

Thank you for your comment, it has hit the mark!

-- 
Yar