of smaller doc.<foo>.mk files, reflecting the functionality they contain.
Long overdue, kudos to the submitter for the carrying out the work.
Also makes the files independent of the system include files that
normally live in /usr/share/mk, making it easier for non-FreeBSD systems
to download and build our docs (an important factor in making it easier
to share our work with other projects).
Finally, it (in theory) lets you build the docs with a r/o doc/ directory.
Changes to the submitted files:
doc.docbook.mk The HTML generation depends on ${DSLHTML}, and the
print generation depends on ${DSLPRINT}. Changing
these files will force a rebuild (which makes testing
changes a little easier).
Removed ${DOC}.doc target. It's a hangover from when
I (mistakenly) thought that Jade could generate MS Word
.doc files.
Added support for using compress(1) to build .Z files
(been on my todo list for ages).
Fixed a couple of typos.
Submitted by: Neil Blakey-Milner <nbm@mithrandr.moria.org>
and encoding for the documentation that's currently being built (e.g.,
'en_US.ISO_8859-1', or 'es_ES.ISO_8859-1'). Used when building packages
to create part of the package file name. Setting this involves an
'interesting' kludge -- suggestions for how better to achieve this within
make(1) welcomed.
package-*:
No need to remove PLIST, it's always overwritten.
Create empty COMMENT and DESCR files if they don't exist. Makes it
easier to test this, without committing COMMENT and DESCR files all
over the tree.
Use the ${LANGCODE} variable in the package name. For example,
the HTML pkg for the FAQ now looks like faq.en_US.ISO_8859-1.html.tgz,
instead of just faq.html.tgz.
${FORMATS} on the command line then it would assume that you wanted to
build a document in the current directory, based on the setting of ${DOC}.
If ${DOC} wasn't set, it defaulted to the name of the current directory.
Any Makefile that includes this, and expects to have documentation built
in the current directory must now explicitly define DOC. All the current
ones do anyway. This should be a non-problem when docproj.docbook.mk is
split out in to smaller, more modular files.
Move the comments for DOC from the non-mandatory to the mandatory
section.
2. Clarify the meaning of DESTDIR, it's changed a little bit since it was
first documented.
3. Initial, tentative support for building pkg_* packages from the
formatted documentation. Needs work, but I've had the patch out for
review for a couple of days, and no comments either way -- so if
people hate it, this should at least spur them on to say so.
# cd /path/to/doc/to/turn/into/a/package
# touch COMMENT DESCR
# make 'FORMATS=this that and the other' package
to build 'n' packages, one per format. "make install" is run as part
of the package dependency, so this will overwrite documentation you
have already got installed.
4. Remove DOC_INSTALL_PREFIX. Should have been DOCDIR from the start.
Default to labelling questions with "Q:" and answers with "A:" when
processing <qandaset>s. In the HTML output, render questions in a larger,
bolder font than the answers. Requested by several people on -doc.
Default to numbering sections. Requested by one person on -doc, who
seemed somewhat confused that I hadn't read his mind and done this three
months previously.
cvs: ----------------------------------------------------------------------
standard doc/ build, and can be turned on for all articles and books
as necessary. What's more likely is that these files (.tar.gz of the
HTML, PS, and other versions) will be automatically generated and placed
on wcarchive, and linked to there instead.
in the case of */FAQ/Makefile, because the FAQs are all in the wrong
place. Things still install properly, but some of the directory paths
are hardcoded. This will be going away ASAP.
Pull in ../Makefile.inc if it exists.
Don't use install(1), use cp(1), chmod(1), and chown(1). That way non-root
users can install the files without install(1) complaining about the
inability to change the owners.
Nuke the "distribute" target. We don't need it where we're going. . .
by the recently committed "Serial Console" section. I had these in my
local tree, and they slipped off my "list of things to commit" somehow.
Prompted by: Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
the overhead of running Jade.
Added an ${EXTRA_CATALOGS} variable if your document needs to be
processed with additional SGML catalogs (currently not used by anything,
but might be some day).
Switched the meaning of ${JADEFLAGS} and ${JADEOPTS} for consistency. All
user-tweakable program options now match ${*FLAGS}.
into a variety of different formats. Contains a lot of code that used
to be in doc/en/handbook/Makefile, the commit log for that file will
probably prove useful as well.
Current version of dsssl-docbook-modular has Japanese option, but
this doesn't satisfy our needs.
Until I write a patch, Japanese stylesheet should be off.
sanctioned hack to indent verbatim environments :-)
Explicitly turn off formatting a <variablelist> as a table, it's still
buggy.
Rename "usen-*" to "en-*", as the usage changed in the underlying
stylesheets. The leader to a <warning> or <caution> should now have
the ":" in the correct position.
HTML files (not all of them, just some of them).
Fix up the broken references to point to the correct files.
This has not touched the release notes in releases/*/*. I'm not sure
whether they should remain as historical record of what was shipped or
not. About 5 of them now have a couple of broken links each, which will
be trivial to fix.
The construct:
<citerefentry>
<refentrytitle>foobar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
is a pain to type, and messes up the pretty-printing of the source code.
Replace every occurence of a entry like that with:
&man.foobar.1;
Adjusting the manual page name and section number appropriately.
The definitions for these entities are stored in man-refs.ent. This
file is in doc/share/sgml because it is not just specific to the Handbook.
I expect the DocBook'd FAQ and Tutorials (coming RSN) to use them as
well.
A new PUBLIC identifier has been created for these entities, and added to
the catalog file.
a mailing list named ``freebsd-security-notification''. it should say
``freebsd-security-notifications'' (with a trailing `s').
Submitted by: Linus Nordberg <linus.nordberg@canit.se>
Doc. Proj. related ports under $PREFIX/share. Update en/handbook/Makefile
with the new paths.
Didn't seem worthwhile to do a repository copy for only three files moved.
clean up the build process a wee bit.
The basic change: instead of cheacking out bits and pieces of the
doc tree into the web build tree, check out the doc tree somewhere
else and put in a few symlinks from the web tree to the doc tree.
On catfish (soon to be hub) for example:
/usr/local/www/build/doc/...
/usr/local/www/build/www/...
where
/usr/local/www/build/www/data/handbook -> ../../doc/handbook
You have to manually put in the symlinks at the moment, but it
works better than the evil CVS hackery.
Also, install with -C to help avoid gratuitous cache-busting due to
gratuitous timestamp twiddling.
Yes, this is supposed to be a new top level in the repository.
For the moment any changes to this area must be cleared by myself
or Jordan. Once the kinks are worked out, the policy will probably
be relaxed.
