documentation is placed under it. Replaces the empty FAQ section and the
only partly completed Handbook section. This is because the information
in here applies to all the documentation under doc/, not just the Handbook.
Move the style guide information out of the-handbook/chapter.sgml and in
to writing-style/chapter.sgml. It doesn't really belong here either, but
we don't have a general style chapter (yet).
Update Makefile to know about this, and use the doc.project.mk file.
Update book.sgml to know about the new chapter.
Remove the old chapters.
of the example HTML and DocBook fragments, which are significant.
Explain where to find the FreeBSD DTD that extends DocBook.
Add a section explaining about books and articles, and the differences
between them.
Added an example of <procedure>.
Be consistent with the white space inside <programlisting>. Make sure
that content starts immediately after the opening tag. Shouldn't make
a great deal of difference, but we should practice what we preach.
Remove the information about <informalexample>, as it seems to be
redundant, and we don't use it anymore.
Correct an error ("]]", should be "]") in the example of including the manual
page reference entities.
on by many people, the SGML conversion has been carried out by the new(ish)
committer, John Baldwin. Cheer's John.
Changes from the submission:
1. It's an article, not a book. I originally thought there was going
to be sufficient content (when you include the committers rules
that are being thrashed out at the moment, and Satoshi's ports
committer stuff) to make this worth being a book. After seeing the
content I changed my mind, so it's an article.
2. Various contractions ("you're" and so on) expanded to make life
a little easier for the translators. Kept one ("Who's Who").
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>
was not bumped after the newbus import. :-( [shame on them].
So I moved it to the ceiling of the closest value. What was claimed to be
the __FreeBSD_version for "newbus" is really for "__deregister_frame_info
dynamic linker bug fix" and EGCS import.
Add 3.3 and 3.2 RELEASE's __FreeBSD_version values.
Obtained from: cvs log src/sys/sys/param.h
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.
to both directories, and make it relative, rather than absolute.
This fixes the case where you might install the docs under one directory
/foo/bar/..., and then want to migrate them elsewhere (to /usr/share/).
With the old scheme, the symlink would start /foo/bar/..., and would
therefore be broken.
A good example of this happening is "make release" :-)
${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.
encoding. This is a band aid fix, just to get it built, and will be fixed
properly in the next day or so, when I can properly analyze the problem.
Now to read the e-mail this has generated. . .
