On Nov 11, 2007, at 23:14, Juan Manuel Palacios wrote:
On Nov 6, 2007, at 8:36 PM, Simon Ruderich wrote:
On Tue, Nov 06, 2007 at 12:05:47PM -0800, [EMAIL PROTECTED] wrote:
Juan Manuel Palacios 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.
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.
[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. :)
_______________________________________________
macports-dev mailing list
[email protected]
http://lists.macosforge.org/mailman/listinfo/macports-dev
