Man pages / Doc strategy

Weissmann Markus mww at
Mon Sep 3 03:30:11 PDT 2007

On 03.09.2007, at 11:05, markd at wrote:

> Weissmann Markus <mww at> 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.
>> 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 W. Weissmann

More information about the macports-dev mailing list