Man pages / Doc strategy

[Weissmann Markus]

On 03.09.2007, at 11:05, markd at macports.org wrote:

> 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.
>

Having only one place for documentation sounds great! I suppose  
regenerating the manpages for every release only could be sufficient.


-Markus

---
Markus W. Weissmann
http://www.mweissmann.de/