Date: Tue, 20 Jun 2000 15:10:09 +0000 From: Nik Clayton <nik@freebsd.org> To: Nik Clayton <nik@freebsd.org> Cc: doc@freebsd.org Subject: Re: Supporting non-DocBook documents in the tree Message-ID: <20000620151009.A732@kilt.nothing-going-on.org> In-Reply-To: <19990827132242.A26830@kilt.nothing-going-on.org>; from nik@freebsd.org on Fri, Aug 27, 1999 at 01:22:42PM %2B0100 References: <19990827132242.A26830@kilt.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--OXfL5xGRrasGEqWY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
On Fri, Aug 27, 1999 at 01:22:42PM +0100, Nik Clayton wrote:
[ Good grief! August last year? I could've sworn this was only a month or
two ago. Here are some quotes from my original message. ]
<snip>
> I think it's probably a bad idea if we insist that documentation that's
> stored under doc/ be in DocBook format. DocBook's a great format, and
> it should certainly be the 'official' DTD of the project, but there
> are certainly going to be some authors who can't use it for some reason.
<snip>
> Each piece of documentation in the tree has to have a Makefile associated
> with it, right? So there's no reason why we couldn't create a new make(1)
> variable (SOURCE_FORMAT ?) that describes what the document's source format
> is, and then the various make(1) rules that do the conversion from
> $SOURCE_FORMAT to html, plain text, Postscript, and PDF all look at
> $SOURCE_FORMAT to decide how to do the conversion.
<snip>
> The overall effect is that this would get more documentation in to the
> tree, where it can be seen by more pairs of eyes, more people can practice
> converting other formats to DocBook, and, through the CVS logs, more
> people can see how you go about converting something from plain text
> or HTML to DocBook, helping to demystify the process.
>
> We live or die by the quality and quantity of documentation that we make
> available, and I don't ever want to see us in a position where someone's
> perfectly good article or book isn't accepted in to the tree because it's
> in the wrong format, and we don't have the manpower to spare to convert
> it to DocBook.
>
> One obvious consequence of this is the FreeBSD 'house style'. As you
> can see when you look at the books and articles that are already in the
> tree, they've adopted a 'house style', because the HTML and other formats
> that are generated are run through the same stylesheets. Obviously,
> J. Random submissions from other people that weren't in DocBook wouldn't
> be in the house style. But I think that's a small price to pay in order
> to get the documentation in to the tree in the first place, where it's
> as useful as possible to the maximum number of people.
>
> Over time, the documents will migrate to the house style as they are
> converted to DocBook.
I've been working on this off and on. Rather than the approach I outline
above, I've used doc.docbook.mk as the basis for a new doc.html.mk.
Suppose someone's submitted a PR with some documentation in HTML (an
article, perhaps), and no one seems to have the time to convert it to DocBook.
In this scenario, we can still bring the documentation in to the tree. To
do this, bring it in as doc/en*/articles/<article-name>/article.sgml.
Then create a Makefile as normal. The only difference in the Makefile is
that you have to include the line
DOCFORMAT=html
somewhere in there.
Then, in conjunction with the attached doc.html.mk, and the patch to
doc.project.mk, you can then do
make 'FORMATS=ps pdf html html-split txt'
(and all the other formats) and things work in the same way as they do for
the DocBook documentation. With one caveat. Currently, doc.html.mk only
supports a few output formats. If you try and do "make FORMATS=html" then
it works. If you try "make FORMATS=ps" then it doesn't work, because
doc.html.mk hasn't been taught how to convert HTML to PS yet.
I DON'T CARE ABOUT THIS.
I *know* that there are tools out there that will convert HTML to PS (and
to sundry other formats as well). That's not what I want to concentrate
on right now. Instead, I'd like people to take a look at doc.html.mk and
tell me how I've screwed up. I'm sure there are easier ways to do some of
the stuff, and I wouldn't be at all surprised if we can merge substantial
chunks of doc.docbook.mk and doc.html.mk to make things easier to follow.
Thoughts?
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
--OXfL5xGRrasGEqWY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="doc.html.mk"
#
# $FreeBSD: doc/share/mk/doc.docbook.mk,v 1.11 2000/04/29 07:46:15 kuriyama Exp $
#
# This include file <doc.html.mk> handles building and installing of
# HTML documentation in the FreeBSD Documentation Project.
#
# Documentation using DOCFORMAT=html is expected to be marked up
# according to the HTML DTD
#
# ------------------------------------------------------------------------
#
# Document-specific variables
#
# DOC This should be set to the name of the HTML
# marked-up file, without the .sgml or .docb suffix.
#
# It also determins the name of the output files -
# ${DOC}.html.
#
# DOCBOOKSUFFIX The suffix of your document, defaulting to .sgml
#
# SRCS The names of all the files that are needed to
# build this document - This is useful if any of
# them need to be generated. Changing any file in
# SRCS causes the documents to be rebuilt.
#
# ------------------------------------------------------------------------
#
# Variables used by both users and documents:
#
# TIDYFLAGS Additional flags to pass to Tidy. Typically
# used to set "-raw" flag to handle 8bit characters.
#
# EXTRA_CATALOGS Additional catalog files that should be used by
# any SGML processing applications.
#
# NO_TIDY If you do not want to use tidy, set this to "YES".
#
# Documents should use the += format to access these.
#
MASTERDOC?= ${.CURDIR}/${DOC}.sgml
KNOWN_FORMATS= html txt pdb
HTMLCATALOG= ${PREFIX}/share/sgml/html/catalog
# ------------------------------------------------------------------------
#
.for _curformat in ${FORMATS}
_cf=${_curformat}
.if ${_cf} == "html"
_docs+= ${DOC}.html
CLEANFILES+= ${DOC}.html
.elif ${_cf} == "txt"
_docs+= ${DOC}.txt
CLEANFILES+= ${DOC}.html ${DOC}.txt
.elif ${_cf} == "pdb"
_docs+= ${DOC}.pdb ${.CURDIR:T}.pdb
+CLEANFILES+= ${DOC}.pdb ${.CURDIR:T}.pdb
.endif
.endfor
#
# Build a list of install-${format}.${compress_format} targets to be
# by "make install". Also, add ${DOC}.${format}.${compress_format} to
# ${_docs} and ${CLEANFILES} so they get built/cleaned by "all" and
# "clean".
#
# However, you only need to do this if _docs has been defined. If it
# hasn't then the user has requested a FORMAT (via "make FORMAT=...")
# that we don't support.
.if defined(_docs) && defined(INSTALL_COMPRESSED) && !empty(INSTALL_COMPRESSED)
.for _curformat in ${FORMATS}
_cf=${_curformat}
.for _curcomp in ${INSTALL_COMPRESSED}
.if ${_cf} != "html-split"
_curinst+= install-${_curformat}.${_curcomp}
_docs+= ${DOC}.${_curformat}.${_curcomp}
CLEANFILES+= ${DOC}.${_curformat}.${_curcomp}
.endif
.endfor
.endfor
.endif
.MAIN: all
all: ${_docs}
${DOC}.html: ${SRCS}
sgmlnorm -c ${HTMLCATALOG} ${.ALLSRC} > ${.TARGET}
.if !defined(NO_TIDY)
-tidy -i -m -f /dev/null ${TIDYFLAGS} ${.TARGET}
.endif
${DOC}.txt: ${DOC}.html
w3m -S -dump ${.ALLSRC} > ${.TARGET}
${DOC}.pdb: ${DOC}.html
iSiloBSD -y -d0 -Idef ${DOC}.html ${DOC}.pdb
${.CURDIR:T}.pdb: ${DOC}.pdb
ln -f ${DOC}.pdb ${.CURDIR}.pdb
${DOC}.tar: ${SRCS}
tar cf ${.TARGET} ${.ALLSRC}
# ------------------------------------------------------------------------
#
# Validation targets
#
#
# Lets you quickly check that the document conforms to the DTD without
# having to convert it to any other formats
#
lint validate:
nsgmls -s -c ${HTMLCATALOG} ${MASTERDOC}
# ------------------------------------------------------------------------
#
# Compress targets
#
#
# The list of compression extensions this Makefile knows about. If you
# add new compression schemes, add to this list (which is a list of
# extensions, hence bz2, *not* bzip2) and extend the _PROG_COMPRESS_*
# targets.
#
KNOWN_COMPRESS= gz bz2 zip
#
# You can't build suffix rules to do compression, since you can't
# wildcard the source suffix. So these are defined .USE, to be tacked on
# as dependencies of the compress-* targets.
#
_PROG_COMPRESS_gz: .USE
gzip -9 -c ${.ALLSRC} > ${.TARGET}
_PROG_COMPRESS_bz2: .USE
bzip2 -9 -c ${.ALLSRC} > ${.TARGET}
_PROG_COMPRESS_zip: .USE
zip -j -9 ${.TARGET} ${.ALLSRC}
#
# Build a list of targets for each compression scheme and output format.
# Don't compress the html-split output format.
#
.for _curformat in ${KNOWN_FORMATS}
_cf=${_curformat}
.for _curcompress in ${KNOWN_COMPRESS}
${DOC}.${_cf}.${_curcompress}: ${DOC}.${_cf} _PROG_COMPRESS_${_curcompress}
.endfor
.endfor
# ------------------------------------------------------------------------
#
# Install targets
#
# Build install-* targets, one per allowed value in FORMATS.
#
# "beforeinstall" and "afterinstall" are hooks in to this process.
# Redefine them to do things before and after the files are installed,
# respectively.
#
# Build a list of install-format targets to be installed. These will be
# dependencies for the "realinstall" target.
#
.if !defined(INSTALL_ONLY_COMPRESSED) || empty(INSTALL_ONLY_COMPRESSED)
_curinst+= ${FORMATS:S/^/install-/g}
.endif
realinstall: ${_curinst}
.for _curformat in ${KNOWN_FORMATS}
_cf=${_curformat}
.if !target(install-${_cf})
install-${_cf}: ${DOC}.${_cf}
@[ -d ${DESTDIR} ] || mkdir -p ${DESTDIR}
${INSTALL_DOCS} ${.ALLSRC} ${DESTDIR}
.for _compressext in ${KNOWN_COMPRESS}
install-${_cf}.${_compressext}: ${DOC}.${_cf}.${_compressext}
@[ -d ${DESTDIR} ] || mkdir -p ${DESTDIR}
${INSTALL_DOCS} ${.ALLSRC} ${DESTDIR}
.endfor
.endif
.endfor
# ------------------------------------------------------------------------
#
# Package building
#
#
# realpackage is what is called in each subdirectory when a package
# target is called, or, rather, package calls realpackage in each
# subdirectory as it goes.
#
# packagelist returns the list of targets that would be called during
# package building.
#
realpackage: ${FORMATS:S/^/package-/}
packagelist:
@echo ${FORMATS:S/^/package-/}
#
# Build a list of package targets for each output target. Each package
# target depends on the corresponding install target running.
#
.for _curformat in ${KNOWN_FORMATS}
_cf=${_curformat}
package-${_curformat}: install-${_curformat}
@echo ${DOC}.${_curformat} > PLIST
@pkg_create -v -c -"FDP ${.CURDIR:T} ${_curformat} package" \
-d -"FDP ${.CURDIR:T} ${_curformat} package" -f PLIST \
-p ${DESTDIR} ${PACKAGES}/${.CURDIR:T}.${LANGCODE}.${_curformat}.tgz
.endfor
#
# A default target, for anything we don't support -- this is normally because
# a target has been created (say, "install-ps") for a format that we don't
# support. This is non-fatal, and we can continue.
#
.DEFAULT:
@echo ${.IMPSRC}: Target not valid for this format, continuing...
--OXfL5xGRrasGEqWY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="doc.project.mk.patch"
Index: doc.project.mk
===================================================================
RCS file: /home/ncvs/doc/share/mk/doc.project.mk,v
retrieving revision 1.2
diff -u -r1.2 doc.project.mk
--- doc.project.mk 1999/09/06 06:53:39 1.2
+++ doc.project.mk 2000/05/12 14:51:34
@@ -67,6 +67,9 @@
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
+.if ${DOCFORMAT} == "html"
+.include "doc.html.mk"
+.endif
.endif
# Subdirectory glue and ownership information.
--OXfL5xGRrasGEqWY--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000620151009.A732>