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.
_______________________________________________
macports-dev mailing list
[email protected]
http://lists.macosforge.org/mailman/listinfo/macports-dev
