Man pages / Doc strategy

[markd at macports.org]

Weissmann Markus <mww at macports.org> writes:
>> Why isn't configure.env supported anymore?
>>
>
>oops - sorry, my fault! I really wanted to say:
>Using configure.env directly should be avoided - we do have a nice  
>set of commands for setting the most used flags at configuration  
>time. If you cannot do without, of course it is still supported.
>
>
>> The new guide documents this option, and does not mention anything  
>> about it being deprecated or unsupported. If it is unsupported, the  
>> guide should state that, and recommend alternatives.
>>
>> http://geeklair.net/new_macports_guide/#reference.keywords.configure
>>
>
>Well yes. We should probably though put our manpages online, too and  
>clearly state that if in doubt the manpage is right.

I personally find the man pages less than adequate.  They were built
piecemeal, and therefore they lack overall coherence; they are just lists
with less structure than they should have.  I intend to make the guide as
authoritative as possible, at least as much as the current man pages.  And
I am striving for more coherently structured information in the new guide
than in the old one or the man pages.  If that can be accomplished,
perhaps the man pages should be reformatted in DocBook and then they could
be regened into man pages daily as is the guide, and then xincluded into
the guide's reference section so as not to maintain duplicate source docs.
 Or at least that seems feasilbe by considering portfile.7 anyway.  If we
got that far I would also want to have a scratchpad where base committers
past their preliminary doc additions for review and inclusion by the doc
team.  No more permanent doc changes in the middle of the night 5 minutes
after hacking on base. Otherwise the docs just degrade over time as
entropy sets in.  Sounds good on paper anyway.  Comments welcome.

Mark