[Please keep me as one of the explicit recipients of this email.
If memory serves me right, Makoto MATSUSHITA wrote:
> takhus> Perhaps the *.TXT files could be periodically regenerated to their
> takhus> current location to 1) avoid a POLA violation and 2) allow for at
> takhus> least some RELNOTES without needing DocBook and doc/ (even if they
> takhus> may be slightly out of date).
> It is true that current.freebsd.org and much of do-it-yourself
> distributions are generated with 'NODOC=YES', since it needs much time
> and disk spaces to process doc.1 target (especially setting up a
> DocBook environment).
My first reaction is, "is doing doc.1 *that* much of a problem"? When
I was testing, it didn't seem like building this consumed much time or
disk space compared to the rest of the make release process (i.e.
building world and several kernels). A checked-out doc/ is 37 MB.
> Removing *.TXT files also makes some difficulties when ordinally "make
> buildworld/installworld" users want to know what changes are made
> (they should change their CVSup configulation file, checkout doc if
> the repository is CVSuped, install DocBook via ports, and run make(1)
> to get a plaintext of release notes).
I think the only recurring cost that people are going to have to do is
to keep a reasonably current copy of doc/. Building the docproj port is
a one-time operation. After that, it takes about 15 seconds of
wallclock time on my workstation to build the TXT version of the release
notes (note that you'll get the SGML sources automatically under src/
> Just like current 'doc' distribution of 'NODOC=YES', it would be helpful
> that *.TXT files are in src/release.
Umm, no, it's not just like the current doc distribution. If you build
a release with NODOC=YES, you don't get any rendition of the FAQ,
Handbook, etc. There's no *.TXT files to fall back on.
Here's my thoughts...for the record, I'm weakly opposed to regen-ing
*.TXT versions: First, I don't want to bloat the repository with oodles
of builds to the *.TXT files. If we do this, it ought to be be fairly
infrequently, like maybe once or twice a month.
Second, regen-ing needs to be done automatically. I'm not going to do
it by hand.
Third, let's assume that there's some interest in actually having
different localized versions of the release notes (note that the
infrastructure supports it). What language do we build for the *.TXT
Finally, there needs to be some boilerplate text on the fallback files
to indicate the generation date of the fallback versions, and a
pseudo-disclaimer that they may be out of date with respect to the
actual state of the code. If we get the automatic generation problem
solved, this one should be easy.
Like I said, I'm weakly opposed to doing this, but I'm also quite
willing to be swayed.