Before: use jade on i386, openjade on !386, provide OPENJADE var for override
Now: detect what's available, when both systems are present, use jade,
provide OPENJADE var for override
This change follows same logic as recent similar change in web.mk
Approved by: keramida (mentor)
First, zip up the template directory from /usr/doc/share/openoffice,
then use 'zip -g slides.sxi content.xml' to append a single file to
the zip archive after content.xml has been created.
Also make this target .OBJDIR clean.
USE_SAXON is set. This doesn't quite work yet.
Also fix a bug in the .fo target that was uncovered when slides for a
presentation are split across multiple XML files.
Norman Walsh's DocBook Slides DTD.
This DTD offers the vocabulary of simplified DocBook for
presentations. Initially, the supported output formats are PDF and
HTML.
XSL stylesheets are used so libxslt is required.
PassiveTeX is used for the PDF generation to convert the XSL-FO
directly to PDF.
This commit moves various TeX definitions out of doc.docbook.mk and
into doc.project.mk, since docbook is no longer the only back-end to
utilize TeX.
An example Makefile would look like :
----
DOCFORMAT= slides
DOC= slides
SRCS= slides.xml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"
---
And an example slides file (slides.xml) looks like :
---
<!DOCTYPE slides PUBLIC "-//Norman Walsh//DTD Slides XML V3.3.1//EN"
"http://docbook.sourceforge.net/releases/slides/3.3.1/slides.dtd">
<slides>
<slidesinfo>
<title>What's new in FreeBSD 5.3</title>
<titleabbrev>FreeBSD 5.3</titleabbrev>
</slidesinfo>
<foil><title>Introduction Slide</title>
<para>Content</para>
</foil>
</slides>
---
You could then build the HTML and PDF versions of the slides by typing
"make FORMATS='pdf html'". Enjoy.
Please coordinate with doceng@ before importing any presentations to
doc/.
Jade is not able to embed images but links them instead, so images have
to be installed with the .rtf document (it's similar to the HTML case).
I added a new format: rtf.tar which is a better solution than using rtf
since the images are not embedded.
make FORMATS=rtf.tar is your friend :)
just after doc.common.mk included. This can be used for various
language specific customizations.
- Remove SP_ENCODING_LIST. Translators should define the SP_ENCODING
variable directly in their doc.local.mk when it is needed.
Discussed with: den
Add KOI8-R to this list
Other encodings can be added after some testing
Note: KOI8-R supported by jade-1.2.1_8 and above
Reviewed by: Dmitry Morozovsky <marck@rinet.ru>, ru
With cleanups from: ru
No objections from: freebsd-doc
stylesheet omits the contents of <filename>, <devicename>,
<programlisting>, and other tags that are likely to not contain real
English words. The output of this stylesheet can then be checked with
'make spellcheck' with far fewer false positives.
is not defined.
- URL_RELPREFIX must always point the top page's URL
(http://www.FreeBSD.org) in relative form, defined in Makefile.
- &url.base; can be used in doc/<langcode>/*. It will be
replaced with the real URL which points the top page.
For translators: Please make sure to define URL_RELPREFIX to
point the top page. The localized docs have different directory
hierarchy in its URL from the English version.
Tested by: den
Replace &url.main; -> http://www.FreeBSD.org
when URLS_ABSOLUTE is set (for release building),
and -> ../../../.. by default (for mirror sites).
Patch was slightly modified by: hrs
Discussed with: des, ceri, hrs, trhodes, simon
The previous fix only worked in some cases, so back it out and add a
more clean fix. This fix also makes "make clean" work as expected again
for the shared PNG images.
The real problem is the assumption in doc.images.mk that the
${IMAGES_PDF} variable only need to contain images converted to PDF
format and not images which are already in PNG format. We need to list
the PNG images in ${IMAGES_PDF} since they might be in a shared image
directory, and if we don't list them in ${IMAGES_PDF} they will not be
copied to the working directory and will therefor not be found during
build.
Prompted by: phantom
After introduction of shared images concept it was not possible to realize
how images should be put into packages, so built images references were
used. It result up tgz file with lots filename which contained of '..'.
In order to workaround this issue I used temporary directory to install
complete packaging document, then generate PLIST based on content of
temporary directory and create actual package then.
Prodded by: The FreeBSD Russian Documentation Project
doc.docbook.mk includes bsd.subdir.mk via bsd.obj.mk which is responsible
for processing of 'SUBDIR' make variable. But since we are handling
'SUBDIR' here explicitly, doing same thing (second time!) via
bsd.subdir.mk's rules makes no sense and only adds disk IO overhead.
It reduces install recursive calls by factor 4.
in the docproj port. TEX, LATEX, PDFTEX, JADETEX, and PDFJADETEX
has been renamed to TEX_CMD, LATEX_CMD, PDFTEX_CMD, JADETEX_CMD, and
PDFJADETEX_CMD for consistency. And TEXCMDS has been renamed
TEX_CMDSEQ because TEXCMDS and TEX_CMD are misleading names.
Discussed on: -doc
- The structure of transtable.xml is revised. <word> should be
bracketed with <group>.
- A sorting order of the FreeBSD mirror sites rendered using
mirrors.xml has been determined by sort(1).
- A template "transtable-lookup" has been added for localization on
word-by-word basis.
- Replace English month names in news.xml, press.xml, and
advisories.xml with numbers that correspond to the names.
The number->name translation is performed on the fly.
- Since information in mirrors.xml is used in www/ tree, it depends on
doc/ tree now. When WITHOUT_DOC is defined it can be built without
doc/ tree, but some information becomes unavailable. For example,
a list of the mirror sites generated in index.html becomes a dummy
one, and calling "transtable-lookup" with a word returns the word
itself.
Neither www/ nor doc/ build should be broken due to this commit, but
until the necessary changes are applied in the localized directories,
the transtable does not work; it simply generates non-localized contents
even if transtable.xsl is used.
- add doc.common.mk, which defines variables, targets, and
dependencies commonly used in www/ and doc/.
- move www/<lang>/includes.xsl to the language independent
directory and split into several files.
- add transtable*.xsl and transtable.xml to support localized
mirror names.
- make doc/{en_US.ISO8859-1,ja_JP.eucJP}/books/handbook/ use
mirrors.xml (mirrors and eresources).
- make www/{en,ja}/index.xsl use mirrors.xml.
For details, please see doc/share/sgml/README.mirrors for the moment.
Reviewed by: simon and Alex Dupre <sysadmin@alexdupre.com>
the lines at column 90, instead of the default 68. This makes the
resulting HTML considerably smaller.
The change also band-aid a problem where Tidy wrap lines which shouldn't
have been wrapped. This can cause extra spaces in the resulting HTML,
e.g. resulting in "( audio/lame)" instead of "(audio/lame)".
Discussed on: -doc
required symbols, by setting the make variable
WITH_ALL_TRADEMARK_SYMBOLS, to any non empty value.
This feature is mainly useful for document writers, to make sure all
trademarks are marked up correctly.
empty and unclosed tags. I used the word "should" because sometimes it
does not work, however most of malformed tags are found now.
That idea came after a talk with Denis Peplin.
bsd.obj.mk already includes bsd.subdir.mk so there is no need
to include it twice.
PR: 52540
Submitted by: "Simon L.Nielsen" <simon@nitro.dk>
Tested with: cd doc/ && make
<indexterms> are sparse. Also add makefile glue so that this may be
invoked on the Handbook or any other document in the FDP tree by
typing "make indexcheck".
Sponsored by: FreeBSD Mall, Inc.
enable it in en_US.ISO8859-1/ and ja_JP.eucJP/.
- Add PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN"
and l10n.ent for entity localization.
- Use share/misc/docbook.css for indentiation of <programlisting>
and <screen>.
- Add some missing $FreeBSD$.
share/images. To link "generic" images (share/images ones) from
Makefiles use IMAGES_EN and to link localized images use IMAGES.
For an example look at en_US.ISO8859-1/books/handbook/Makefile
- WITH_INLINE_LEGALNOTICE (for HTML only):
do not render <legalnotice> as a separate file if defined.
- WITH_ARTICLE_TOC:
generate TOC for documents whose root element is <article> if defined.
- WITH_BIBLIOXREF_TITLE:
for cross references to bibliography entries, use the title of
the entry as the cross reference text, if defined.
textproc/scr2txt must also be on the system.
The .txt files are created on the fly with .png ones. This is not
perfect, but it allows mirrors to build docs.
localized docs.
For example in the Handbook Makefile, an image entry will be similar to:
IMAGES = ../../../en_US.ISO8859-1/books/handbook/install/userconfig.scr
the image will be built in that directory and then installed in the right
localized place at installation time.
Some versions of ghostscript (7.04) have problems with the use of
relative path when the arguments are passed by peps; a fix was
added.
Reviewed and discussed with: murray
Add support for using the XSL stylesheets to generate HTML output using
XSLT transforms, rather than using JadeTeX. So (assuming you have
installed xsltproc from ports/textproc/libxslt, and the docbook-xsl
stylesheets), you can now do
make STYLESHEET_TYPE=xsl FORMATS=html
and get HTML output that way.
'xsl' a different set of rules are invoked to use an XSL toolchain
(processors, stylesheets, and so forth) to convert the DocBook to the
various different output formats.
I haven't actually written the rules that are invoked when this knob is
set to 'xsl'. But how hard can it be. . .
If defined, EPS files are run length encoded before being integrated
into the PostScript output.
"make book.ps" currently generates a 96 megabyte file.
"make RLE=1 book.ps" generates a 16 megabyte file.
If we added a tool to use better (LZW) compression for the eps
screenshots and such, then we could reduce this number further.
Don't make the assumption that source files are writable.
The FDP infrastructure has a few constructs of the form
"cp foo bar; cat baz >> bar". This breaks if foo isn't
writable (as is frequently the case in P4 work directory).
stylesheets. To get around this, append the filename specified in the
'CSS_SHEET_ADDITIONS' variable (if defined) to the end of the default
CSS stylesheet. This allows us to add document-specific stylesheet
rules while still supporting braindead browsers and reusing the
default CSS code.
CURDIR. This causes problems when one wants to have multiple doc/
trees checked out at once because it requires every tree to be in a
directory called "doc"; i.e., one must have <name-of-tree>/doc/
instead of just <name-of-tree>/ like one can do with src/. Mitigate
the pain by making it possible to tell the build infrastructure what
the doc prefix is called; this still isn't perfect since it requires
that optional features such as two-sided output and justification work
for PDF files, not just PostScript.
PR: docs/32849
Submitted by: Peter Johnson <freebsd@bilogic.org>
possible generated files (make clean is called for all known formats).
It can be useful when default FORMATS for document has different value
than was used in build.
Reviewed by: nik
to process generated HTML. This not cause any side effects except
leaving some character entities in their numeric form instead
converting them into alphabetical notation (< instead of <),
but since all browsers understand such cases it is not a problem.
This commit should make all translations tidy clean, since
tidy should not arise entities conversion problem as it did
for long time before. Therefore all occurences of manual settings
of TIDYFLAGS and NO_TIDY declarations for translations are removed.
No objections from: -doc
Requested by: Russian and Japanese translation teams
* Add a new document-specific variable, HAS_INDEX, to specify if a
given document is marked up with <indexterm> entries.
* Rework the index support so that both HAS_INDEX and GEN_INDEX are
checked before trying to generate an index for a document.
* Only create index.sgml if both HAS_INDEX and GEN_INDEX are set.
This allows us to recursively build the documentation tree with
GEN_INDEX=1 and have it only try to create an index (very time
consuming) for the few documents that are ready for this. Previously,
running "make GEN_INDEX=1" from the top of the doc tree would look for
index terms in every single document.
With this, I hope we can start building our docs with GEN_INDEX set on
freefall so that users browsing the HTML docs will get the benefit of
the index we've been hiding in CVS for 6 months.
Also fix several minor bugs here, such as leftover files not being
deleted after 'make clean'.
PR: docs/31131
Submitted by: Cyrille Lefevre <clefevre@citeweb.net>
to make the paragraphs right justified using TeX's default hyphenation
rules. We still must add some hooks to certain elements (URLs) to
deal with special cases that TeX can't hyphenate well.
TWO_SIDE - If defined, two sided output will be created. This
means that new chapters will only start on odd
numbered (aka right side, aka recto) pages and the
headers and footers will be aligned appropriately
for double sided paper. Blank pages may be added as
needed.
BOOK_OUTPUT - If defined, this will set all of the other
print-output options that can significantly increase
the build time, but make for much nicer looking
output.
To implement the two sided output, we need to override a TeX variable
to control the behavior of the JadeTeX macro package. So this also
introduces a TEXCMDS variable that can be set with additional TeX
commands that should be run before processing the input TeX document.
In the TWO_SIDE case, we simply set it to \def\PageTwoSide{1}
This target finds all <programlisting role="pgpkey"> elements in the
Handbook and writes out a flat text file suitable for importing into
PGP or GPG.
This can be used in the web build to automatically update the public
keyring of FreeBSD developers.
JADEFLAGS to set variables such as %generate-article-toc%. However,
JADEFLAGS is also passed to nsgmls, which doesn't, and shouldn't,
understand -V. The Makefiles which do this are correct, because the
name--JADEFLAGS--implies that it will only be passed to Jade, not to
nsgmls, too. Furthermore, simply not passing JADEFLAGS to nsgmls is
not okay, since nsgmls *does* need the -i flags used to
include/exclude certain parts of the document.
Remedy this by breaking up JADEFLAGS into itself and SGMLFLAGS. The
latter will be passed to all SGML processors such as nsgmls and Jade.
The former will only be passed to Jade. The -V flags should stay in
JADEFLAGS, and the -i flags should be moved to SGMLFLAGS.
This fixes `make lint` for documents which use -V via JADEFLAGS.
Reviewed by: bmah
support.
This option prevents section labels from being numbered after the third
level.
make FORMATS=ps :
"N.N.N Section Title"
"N.N.N.N really specific topic"
"N.N.N.N.N really-really specific topic"
make MIN_SECT_LABELS=1 FORMATS=ps :
"N.N.N Section Title"
"really specific topic"
"really-really specific topic"
The section titles are still bold, spaced away from the text, and
sized according to their nesting level.
NICE_HEADERS is a set of print-only enhancements, however the HTML
backend is invoked whenever an index is generated, so we should not
touch JADEOPTS directly and should instead modify the .tex-ps target
directly.
chapter headers that you may find more aesthetically pleasing than the
rather spartan chapter headers in Norm's print stylesheets. This
option only effects print output formats for English language books.
Also move the local-en-label-title-sep customization from share/sgml
to en_blah/share/sgml since the best values for this customization
depend on the locale.
This changes (make FORMATS=ps) :
Chapter 7. Users and Basic Account Management
7.1. Synopsis
into (make NICE_HEADERS=1 FORMATS=ps) :
Chapter 7
/Users and Basic Account Management/
7.1 Synopsis
More work needs to be done for the NICE_HEADERS case to enhance the
output, but I think its an improvement.
one must run a `make clean' (or `rm docbook.css') or the stylesheet is not
updated, regardless of whether or not it's been updated since the last
build.
convert graphics. Change the default from 82 to 100, for clearer images.
PR: docs/28237
Submitted by: G. Adam Stanislav <adam@whizkidtech.net>
While I'm here, include some suffix rules to convert .scr files to .png
files. Nothing uses these, yet, but should do shortly.
isn't a problem yet, but I did run into it in my local builds a few
times, and I thought it'd be better to raise it now to make sure
nothing magically breaks later.
Silence by: -doc
<aph> running, for instance, "jadetex '\nonstopmode\input{$<}'" is much
better since it won't crash out an automated build as badly
<nik_> Huh?
<aph> it will fail rather than kick you into a TeX prompt and wait for output
<aph> I guess in BSD make that would be:
<aph> jadetex '\nonstopmode\input{${.ALLSRC}'
Submitted by: Adam di Carlo <adam@onshore.com>
will be run to generate index.sgml, an automatically generated index for
the document. This is also added to the list of dependencies.
2. Add a DOCBOOKSUFFIX variable, defaulting to "sgml", so we can write
MASTERDOC?= ${.CURDIR}/${DOC}.${DOCBOOKSUFFIX}
Requested by: Michael Wiedmann <mw@miwie.in-berlin.de>
Linux Documentation Project
3. Set the DSSSL 'openjade' variable to #t if we're processing with
OpenJade.
4. Work around a bug in the stylesheets. If we split the <legalnotice>
out in to a separate file it isn't added to the HTML.manifest. Check
for it by hand, and include it if necessary.
Extend the image support. Now handles the "install" part for HTML, PS, and
PDF, as well as packaging.
Better support for images in the PDF output. I'm still trying to figure out
how to get good quality PDF from EPS source though.
For producing text-only docs, we need to have a second HTML target.
The PS and PDF targets (which depended on a .tex file) have been split
out so that they each depend on their own .tex-${format} file, to get
the image formats correct.
with SYSTEM, and using instead PUBLIC entities gained from the catalog
in the directory of the language the document belongs to, or the
language-neutral entity. Now we always use default.dsl as our dsl
master, and it grabs the necessary magic from the catalogs.
b) Fix the always-out-of-date imagelib problem with some make(1)-fu.
Approved by: nik (ages ago)
target uses -- this ensures that any options (such as "OMITTAG NO") that
are used when building the docs are also used when linting them, so that
errors don't slip through the cracks.
Prompted by r1.93 of the FAQ.
Admittedly, this is a hack, and the real solution is to sanitize FORMATS
by removing any words that aren't in KNOWN_FORMATS. This fixes release
since releases uses 'html html-split txt' for FORMATS when it compiles and
installs the docs.
LOCAL_LIB_IMAGES_DIR should be a path component, not a complete path, so
remove ${.CURDIR}.
doc.docbook.mk
Set the directory for image installation correctly, and ensure that the
directory exists before we try and do anything with it.
These should fix the installation problems people are having with the
primer. There's still an outstanding bug -- make(1) thinks that the
local library images are out-of-date with respect to the ones in
share/images for some reason. This forces a rebuild each time. I'm
still looking at that.
1. Listing LIB_IMAGES as a dependency on certain targets, to ensure
that library images are pulled in correctly.
2. Create a new FORMAT, html.tar, to cater for the case where we might
be producing a single .html file, but we need to tar that up for
distribution and the tar file needs to include all the images.
3. Update the various install-* targets to include the images.
4. Update the package-* targets to include the images
While I'm here, pull out the .doc target. For some reason I thought our
tool chain could produce Microsoft Word .doc files. It can't.
sheet definitions for that language only. Each file reads in the defaults
from the master share/sgml/freebsd.dsl file, and adds overrides, or new
definitions, as necessary.
Move the per-language hacks from share/sgml/freebsd.dsl in to
<lang>/share/sgml/freebsd.dsl as necessary.
Add links to the -questions and -doc mailing lists to the bottom of the
generated HTML output for some languages. The -questions link will
become a link to Greg's "Getting the most from questions" document when
I bring that in, but I haven't done that yet, and I didn't want these
patches hanging around my local tree.
This was the real reason for making freebsd.dsl language local, as it
makes it much easier to translate generated text, such as the text of
the links, without polluting share/sgml/freebsd.dsl.
Update doc.docbook.mk to use the new, per-language freebsd.dsl file when
building the docs. While I'm here, update .pdb generation so that it
creates a symlink to ${CURDIR:T}.pdb as well (e.g., the Handbook generates
"book.pdb" and "handbook.pdb"). This makes it easier to install more than
one document on a Palm, because two docs called "book.pdb" or "article.pdb"
can not co-exist.
Tidy cannot handle EUC-JP codepoint range correctly with -raw option.
I will try to fix this problem, but temporary disable to use tidy in
Japanese Handbook and FAQ.
is superior, and the various translation teams are fine with it.
Use iSilo instead of pilot-makedoc to produce Palm compatible files. It
works from the HTML and retains the formatting (including the internal
links) making it much nicer to work with than the output from pilot-makedoc.
works, but isn't great (at least in SmartDOC). Still, if you want to carry
the FreeBSD FAQ on your Palm (or the Handbook for that matter) it's a start.
PR: docs/13439
Submitted by: Slaven Rezic <eserte@cs.tu-berlin.de>
the .html files that have been built, instead of all of them. Fixes a bug
where "make FORMATS='html-split html'" would only update the split HTML
files.
Reported by: Mark Ovens <mark@ukug.uk.FreeBSD.org>
Submitted by: Neil Blakey-Milner <nbm@mithrandir.moria.org>
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.
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. . .
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.
