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