1.6 release?

[Juan Manuel Palacios]

irss
On Nov 6, 2007, at 8:36 PM, Simon Ruderich wrote:

> On Tue, Nov 06, 2007 at 12:05:47PM -0800, markd at macports.org wrote:
>> Juan Manuel Palacios <jmpp at macports.org> writes:
>>> 	Content organization put aside, we have to figure a way to tie  
>>> "make
>>> man" in the doc-new dir with our make system in trunk/base, so that
>>
>> 1)
>>> the regular "./configure && make && make install" dance (called
>>> either when installing from source of while selfupdating) gets a set
>>> of shiny new pages....
>>
>> 2)
>>> or are you thinking of regen'ing them manually
>>> in trunk/doc-new and copying them over to trunk/base/doc/ when you
>>> think it's OK to "cut a release" for them?
>>
>> I would think option 1 would be best, unless there is a consensus
>> otherwise.  I'm cc'ing doc team on this.  I'd prefer "live" docs  
>> with head
>> as now.  I haven't thought about what Makefile changes would be  
>> necessary,
>> and since the other doc team members are better programmers, I  
>> probably
>> wouldn't be the one to do it anyway.
>>
>> Mark
>
> Hi,
>
> I also think 1) is the best way.
>
> But there is one problem: To make sure everybody gets the  
> documentation when
> checking out a copy from svn we either have to move the  
> documentation in the
> base/doc directory or use svn:externals so it gets downloaded.


	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. Or am I misunderstanding something?

>
> And as not everybody has a docbook installation on their computer


	But as it seems that I'm not mistaken, 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...


> the man
> pages should be generated before each release and included in the  
> source
> tarballs.


	Hopefully not only when putting a MacPorts release together, as that  
would leave all those working on trunk with outdated documentation in  
the intervening time. You guys should update them in base/ from the  
docs/ dir whenever you feel the updates to the sources warrant it.


> But we have to be "careful" no one modifies the man pages as they
> are then automatically generated and so any change will be  
> overwritten.

	Maybe one of you could place permanent svn locks (and the svn:needs- 
lock property) on the man pages in the base/doc dir? We would get  
other developers to agree not to steal them, so that only you guys can  
update the pages. This would further emphasize that documentation  
patches should be uploaded to http://trac.macports.org/projects/macports/milestone/Website%20%26%20Documentation 
  rather than committed directly.

	Anyone should feel free to suggest another approach if this one is  
too lame. I like the idea of having our documentation centralized, but  
placing a dockbook requirement on building base just for the sake of  
the man pages leaves a bad taste in my mouth.

>
> We could add a target to the Makefile of the documentation to move the
> generated man pages to a given directory, which could be useful for  
> developers
> to simplify the update process for them.


	Feel free to implement your best solution, if we do go the route of  
copying the generated man pages over from the docs dir.

	Regards,...


-jmpp