'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).
<filename role="package">. The <port> tag as it was had two major
defects: (a) the name is ambiguous (does "port" mean "architecture"?
how about "TCP/UDP port"?), and (b) it introduces a non-standard (to
DocBook) tag, which is generally assumed to be evil.
Moral support by: bmah, keramida, mwlucas, roam
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
to fix a bug that would cause footnote numbering to be messed up if
using %footnote-ulinks% and we had any empty <ulink></ulink> elements
in a document. (This happens a lot in the release documentation.)
This change has been submitted to the DocBook bug database on
SourceForge as bug #502066. When it gets included into the
DocBook DSSSL distribution and the corrected version gets incorporated
into the FreeBSD Ports Collection, I'll back out the change in our
(FreeBSD's) stylesheet.
combination of %footnote-ulink% and bop-footnotes not generating any
URL footnotes (although other footnotes in documents were
correct). freebsd.dsl contains a modified definition of the
ulink element as defined in dblink.dsl from the DSSSL print stylesheet;
unfortunately it was missing some lines of code, which we restore.
As of this commit, no document in the FDP uses %footnote-ulink%,
although the release documentation will enable it shortly.
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
in the FAQ to use these. (Presumably there'll be others.)
While I'm here, add an entity for the current release's errata file.
Heavily based on the last patch in the PR, modified to be consistent
with the way that the Website build defines similar entities.
PR: 30202
Submitted by: Michael Lucas <mwlucas@blackhelicopters.org>
* 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>
entities throughout the install chapter. These need to be defined
with so that these buttons don't wrap across lines.
This prevents :
"Press the [
OK ] button"
from showing up in the print or HTML output.
thinks that it must never output something like "_" to the TeX
backend, and should instead use \char{95}. The package we are using
to hyphenate URLs, url.sty, is designed to allow URLs without worrying
about such things, and will literally display the \char{95} without
this patch.
of the functions to get correct page numbering for two sided output.
This code will also have to insert some blank pages to make sure part
and chapter headers always start on a verso page. This is an
improvement, but it is also a work in progress that should be in the
tree so others can experiment with it.
The most visible impact is that the Chapter 1 now starts on page 2
instead of page 1. Part I now starts on page 1 instead of xviii.
When this is done properly, Chapter 1 will start on page 3.
prevents the majority of the remaining margin overflows. However,
this solution isn't very elegant in that it completely ignores
<replaceable>s inside of a <filename> element. The normal TeX that
gets output inside of \url{..} confuses TeX, so we must simply process
the children of replaceable without doing any additional formatting
inside of the \url{..} (such as putting the text into italics).
More work needs to be done on this.
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}
by default for printed output. It turns out that this combination results
in URLs running of the right margin of the printed page.
This back-out is a temporary work-around to fix the PS/PDF
documentation for the impending 4.4-RELEASE.
Approved by: murray
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.
specific construction rule instead of duplicating code when we want to
conditionally alter the stylsheets.
Suggested by: Norman Walsh
Referenced in: ISO/IEC 10179:1996(E) p180-181
new man page entity with the right format into the right place.
Revs. 1.82-1.84 of man-refs.ent are a good, although perhaps extreme,
example of what this is trying to prevent. check-manref.sh makes sure
that the entities in man-refs.ent are in the right order, which is
necessary for add-manref.sh to work properly.
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.
appropriate.
I've specifically left JKH's attribution for the "FreeBSD History"
section in tact, since this is a first person account of the history
of FreeBSD and as such the author needs to be identified in place.
This could probably be marked up differently, but its clear that this
section is different from all of the other "contributed by XXX" in the
Handbook.
Also add support for <sect1info> and <sect2info> to the stylsheet so
that these attributions get displayed as they have been.
Local-file URLs are encoded as file://localhost/path/file which is
fine for HTML but this looks ugly when printed.
Add a function to chop off the "file://localhost" so that the above
URL would be printed as "/path/file" but still link to
"file://localhost/path/file" for HTML output.
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.
don't have to keep this number updated at N different places
throughout the doc tree.
Update 3 instances of "4,000" in the Handbook to use this new entity.
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.
relevant functions to the DSSSL stylesheet.
The default behavior is for print output formats to just display PGP
fingerprints unless you use `make WITH_PGPKEYS=1 FORMATS=ps'. This new
default behavior reduces the size of Appendix E from 52 pages to 9
pages, and that could be trimmed down more with a more efficient
layout for the fingerprints (does each entry really warrant a new
section header?)
Knob requested by: Chris Costello
Discussed on: -doc
on -doc who don't share my sense of the aesthetic
Try a better fix at the 'stair stepping' in lists -- the previous fix only
worked for lists that were children of the BODY element, so it didn't have
any effect on those that were (for example) enclosed inside a
<DIV CLASS="PROCEDURE">.
list items, but not to the bullets/marks. Where it used to appear as
1.
This is item one.
2.
This is item two.
and so on, it should now appear as
1. This is item one.
2. This is item two.
Based on a suggestion from Haikal Saadh <wyldephyre2@yahoo.com>.
adds a new mediaobject handler to simplify the output HTML so that
images no longer overlap the text and other nearby images.
The output HTML used to look like this :
<div class="MEDIAOBJECT">
<p><img src="fig2.png"></p>
</div>
The problem was that the image would be displayed on top of nearby
text or image elements completely obscuring the previous contents
rather than doing proper page layout. With this change, the above now
simply looks like this :
<img src="fig2.png">
An alternative solution would be to fix docbook.css, but I think that
the problem stems from the way that different browsers implement CSS.
It is easier to just fix it here at the DSSSL level.
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.
special formatting for questions, as the stylesheets now do this.
Interested parties can look at http://people.freebsd.org/~nik/faq-css/
for an idea of how the new stylesheets render.
should speak for themselves. Using these will significantly improve
consistency through the doc tree. Right now--before most of the
documents use these--there are five or six different spellings of
"FreeBSD-STABLE", even in the same document! &os; was added for
completeness.
Approved by: -doc
This isn't normally an issue because no one in their right mind will
stick a <link> inside another <link>. However, we have entities which
create links, such as &man.*;, &a.*;, etc. It's nice to be able to
use these inside links. To deal with this..
Introduce a create-link procedure which will be used to replace (make
element gi: "A" ...) constructs. This procedure creates a link as
specified only if the can-link-here procecure (described below)
returns #t. If the latter returns #f, it will print the link text
without the link.
The (also new) can-link-here procedure returns #t if it determines
that it's okay to make a link in the current context, and #f
otherwise. Currently, it does its check by figuring out whether the
current context is within a <title> or <question> tag. This is not
ideal because it doesn't catch all cases, but it's a lot better than
nothing. As the other cases are discovered, this procedure can be
modified.
being rendered any differently than <username>, but it's very
confusing to write markup with both user and group names in close
proximity, and both marked up with <username>.
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
in the text and let it be a link to the bibliography entry.
Note: The functionality needs JADEFLAGS=-Vbiblio-xref-title in the Makefile
Reviewed by: nik, freebsd-doc (original version)
Original by: nik
man page references (&man.ls.1;, etc) are converted in to links to the
man->HTML CGI on freebsd.org. Defaults to off.
Redefine the code for the <citerefentry> element to use this variable.
don't indent body text. This reduces the size of the Handbook's PS file
by about 1MB, and has similar (although less dramatic) effects on the
other documents.
<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.
tree that I wasn't quite ready for. It may as well stay in now though.
In order.
1. Pull out the code that deals with <segmentedlist>, the regular
stylesheets handle that now.
2. Change how $email-footer$ is handled. This requires changes to the
<lang>/share/sgml/freebsd.dsl files, to come very shortly.
3. Redo warning and caution label support. This is no-op, as Norm's
sheets don't support this the way I want yet.
4. Remove a useless comment.
5. Pull out the experimental docinfo stuff, it doesn't work.
6. Pull out the special handling of <literallayout>, the regular
stylesheets handle that now too.
generated HTML link to the legalnotice, if the document has one.
Requested by several people on -doc (all of whom probably thought this
would be quite a lot of effort, heh heh heh).
This has the useful side effect of generating bookmarks in the PDF file,
which programs like Adobe Acrobat Reader can use to provide a navigable
table of contents in a side window. This only seems to work with OpenJade,
but the option doesn't cause Jade any problems.
now-deprecated osf1(8). -CURRENT doesn't have these anymore, but the
-STABLE branches do; plus it's a little odd to try to write about the
scripts' removal without these entries.
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.
with a number, and not just a big "Q". No idea what the hell I was
thinking when I did that.
Override generate-anchor in the master stylesheets, so that the names
(i.e., the <a name="...">) in the HTML output for questions is Qx.y.,
where x.y is the question number. This is much less likely to change
than the AENxxxx format, which changes with every addition or deletion
to the FAQ, so it's much easier for people to link to specific questions
within the FAQ now.
A few whitespace/indentation changes with existing code.
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.
