1.6 release?

[Juan Manuel Palacios]

On Nov 12, 2007, at 2:09 AM, Ryan Schmidt wrote:

>>>
>> 	I originally thought 1) was the best approach too, but from what I  
>> understand that would impose a dockbook requirement on all those  
>> who simply want to build base for whatever purpose, and I seriously  
>> dislike that idea.
> [snip]
>> I would very much prefer the second approach: that you guys "cut  
>> releases" of our man pages and upload them to base/ when you feel  
>> it's most appropriate; but...
>
> I'll voice a mild preference for #1, sort of. That is, I think it's  
> ok to require additional software installed for users of trunk.  
> These users will likely already have a prior version of MacPorts  
> installed and can simply "sudo port install docbook-xml" and then  
> when they build MacPorts from trunk they get the very latest  
> manpages automatically. That's good.
>
> Users of downloaded versioned distribution archives, however (like a  
> macports-1.6.0.tar.bz2 source archive), should not have to do that.  
> Pre-generated manpages should be included with such source tarballs.
>
>
> #2 seems problematic to me, and besides is against the Subversion  
> tenet of not committing things to the repository that can be  
> generated. Sometimes it's useful to do so, but in this case I don't  
> think it's best. You run into problems of communicating to people  
> that they should not commit to those generated files but rather to  
> the original sources and then regenerate the files. Having one user  
> lock the files is not great; perhaps we currently only have one user  
> writing the documentation, but hopefully more will get involved at  
> some point. And telling people to regenerate the manpages and commit  
> them whenever they feel it's appropriate is no good, because either  
> the person will say that every change is significant and worthwhile  
> (why else would the change be made?) so after every change they have  
> to regenerate the manpages and commit them, or the person says it's  
> too complicated (or forgets) and never regenerates the manpages. In  
> summary, I don't like it. :)


	Though I realize manually uploading the regen'd man pages from the  
doc dir into base and svn-locking the the latter is a lame approach (I  
agree with all the flaws you point out), I seriously dislike the idea  
of imposing such hefty requirements as docbook2X --and its  
dependencies, uuugghhh! -- (for docbook to man page format conversion)  
on base for the sole purpose of rebuilding the man pages. I would  
seriously prefer we find an alternative to both these approaches, #1  
and #2, as the original idea of concentrating our documentation in a  
single place is a sound one but I feel we still haven't figured out  
the most appropriate implementation path.
	
	Feedback is most welcomed! Regards,...


-jmpp

PS: I suppose that until we find a suitable alternative, carrying on  
with our old man pages in base and new sources in the doc dir will  
have to be the way to go. Mark, Simon and Maun Suang should update the  
trunk/base/doc dir once trun/doc-new is ready for prime time, and  
we're all just gonna have to agree to not touch trunk/base/doc lest  
our input there is rewritten by their work. Committers/contributors  
are most encouraged to submit their documentation patches/enhancements  
as attachments to tickets in the "Website & Documentation" milestone  
in our Roadmap.