From: Michael Smith Date: Thu, 23 Jun 2005 03:28:56 +0000 (+0000) Subject: Added several parameters for manpages output. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5d8f00351fa0f5691f1831736c97c4aa7e1f430e;p=docbook-dsssl Added several parameters for manpages output. I have chosen to use a man.* naming strategy for all man-only params (which these all are), even though in some cases the params are basically the same as existing params (man.alignment and man.hyphenate are basically same as the corresponding FO params, man.output.encoding is same thing as chunker.output.encoding, man.output.quietly is same as chunk.quietly). One reason I went with create new params instead of reusing existing ones is that this allows default values to be used for manpages output that are different than the ones for whatever other output format. For example, I set default for man.alignment to "left" and man.hyphenation to "false". The corresponding FO params have defaults of "justify" and "true". And, as far as the man.* naming strategy, yeah, I guess it it redundant. If, for example, all the HTML-only params started with html.*, I guess it might not be so great idea. Or maybe it would be. Anyway, I don't think there will probably ever be more than 30 man.* params total (god help us). And for developers at least, I think it is helpful to be able to sort params by prefix if they want to. Because, well, we now have 434 separate files in the params/ directory. Going through those to find, say, just the ones that relate to manpages output is a whole lot easier if they all start with the same prefix. --- diff --git a/xsl/params/man.alignment.xml b/xsl/params/man.alignment.xml new file mode 100644 index 000000000..02a71740c --- /dev/null +++ b/xsl/params/man.alignment.xml @@ -0,0 +1,22 @@ + + +man.alignment + + + +man.alignment +Specifies default text alignment for man-page output + + + +left + + +Description + +This parameter controls the alignment (roff +"filling-and-adjusting" behavior) used for most body text in man-page +output. + + + diff --git a/xsl/params/man.charmap.subset.profile.xml b/xsl/params/man.charmap.subset.profile.xml new file mode 100644 index 000000000..a7b292691 --- /dev/null +++ b/xsl/params/man.charmap.subset.profile.xml @@ -0,0 +1,259 @@ + + +man.charmap.subset.profile +string + + +man.charmap.subset.profile +Profile of character map subset to use in place of full map + + + + + +@*[local-name() = 'class'] = 'roffControl' or +@*[local-name() = 'class'] = 'C1ControlsAndLatin-1Supplement_symbols' or +@*[local-name() = 'class'] = 'GeneralPunctuation_spaces' or +@*[local-name() = 'class'] = 'GeneralPunctuation_dashes' or +@*[local-name() = 'class'] = 'GeneralPunctuation_quotes' or +@*[local-name() = 'class'] = 'GeneralPunctuation_bullets' or +@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or +@*[local-name() = 'name'] = 'WORD JOINER' or +@*[local-name() = 'name'] = 'SERVICE MARK' or +@*[local-name() = 'name'] = 'TRADE MARK SIGN' or +@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE' + + + + +Description + +If the value of the +man.charmap.use.subset parameter is non-zero, +The character-map subset specified by the +man.charmap.subset.profile parameter is used +instead of the full roff character map. + +The value of man.charmap.subset.profile +is a string representating an XPath expression that matches attribute +names and values for output-character elements in the +character map. + +The attributes supported in the standard roff character map +included in the distribution are: + + + character + + a raw Unicode character or numeric Unicode + character-entity value (either in decimal or hex) + + + + name + + a standard full/long ISO/Unicode character name (e.g., + "OHM SIGN") + + + + class + + a "block" name, which consists of a standard Unicode + block name but with spaces removed and with, in some cases, a + _something string appended; for the + full list of block names supported in the standard roff + character map, see . + + + + entity + + an ISO entity name (e.g., "ohm") + + + + string + + a string representating an roff/groff escape-code (with + "@esc@" used in place of the backslash), or a simple ASCII + string + + + + +The value of man.charmap.subset.profile +is evaluated as an XPath expression at run-time to select a portion of +the roff character map to use. You can tune the subset used by adding +or removing parts. For example, if you need to use a wide range of +mathematical operators in a document, and you want to have them +converted into roff markup properly, you can might add the following: + +@*[local-name() = 'class'] ='MathematicalOperators' + +That will cause a additional set of around 67 additional "math" +characters to be converted into roff markup. + + +Depending on which XSLT engine you use, either the EXSLT +dyn:evaluate extension function (for xsltproc or +Xalan) or saxon:evaluate extensio function (for +Saxon) are used to dynamically evaluate the value of +man.charmap.subset.profile at run-time. If you +don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that +supports dyn:evaluate -- you must either set the +value of the man.charmap.use.subset parameter +to zero and process your documents using the full character map +instead, or set the value of the +man.charmap.enabled parameter to zero instead +(so that character-map processing is disabled completely. + + +An alternative to using +man.charmap.subset.profile, is to create your +own custom character map, and set the value of +man.charmap.uri to the URI/filename for +that. If you use a custom character map, you will probably want to +include in it just the characters you want to use, and so you will +most likely also want to set the value of +man.charmap.use.subsetto zero. +You can create a +custom character map by making a copy of the standard roff character map provided in the distribution, and +then adding to, changing, and/or deleting from that. + + +If you author your DocBook XML source in UTF-8 or UTF-16 +encoding and aren't sure what OSes or environments your man-page +output might end up being viewed on, and not sure what version of +nroff/groff those environments might have, you should be careful about +what Unicode symbols and special characters you use in your source and +what parts you add to the value of +man.charmap.subset.profile. +Many of the escape codes used are specific to groff and using +them may not provide the expected output on an OS or environment that +uses nroff instead of groff. +On the other hand, if you intend for your man-page output to be +viewed only on modern systems (for example, GNU/Linux systems, FreeBSD +systems, or Cygwin environments) that have a good, up-to-date groff, +then you can safely include a wide range of Unicode symbols and +special characters in your UTF-8 or UTF-16 encoded DocBook XML source +and add any of the supported Unicode block names to the value of +man.charmap.subset.profile. + + + +For other details, see the documentation for the +man.charmap.use.subset parameter. + + + Supported "block" names + + Below is the full list of "block" names supported in the + standard roff stylesheet provided in the distribution, along with a + description of which codepoints from the Unicode range corresponding + to that block name are supported. + + + + C1ControlsAndLatin-1Supplement_symbols (x00a0 to x00ff, symbols) + + + C1ControlsAndLatin-1Supplement_letters (x00a0 to x00ff, letters) + + + LatinExtended-A (x0100 to x017f, partial) + + + LatinExtended-B (x0192 only) + + + SpacingModifierLetters (x02b0 to x02ee, partial) + + + GreekandCoptic (x0370 to x03ff, partial) + + + GeneralPunctuation_spaces (x2000 to x206f, spaces) + + + GeneralPunctuation_dashes (x2010 to x2015) + + + GeneralPunctuation_quotes (x2000 to x206f, quotation marks) + + + GeneralPunctuation_daggers (x2000 to x206f, daggers) + + + GeneralPunctuation_bullets (x2000 to x206f, bullets) + + + GeneralPunctuation_leaders (x2024 and x2025) + + + GeneralPunctuation_ellipses (x2026) + + + GeneralPunctuation_primes (x2032 to x2034) + + + GeneralPunctuation_wordjoiner (x2060) + + + GeneralPunctuation_other (x2000 to x206f, except for + anything in any of the other GeneralPunctuation_* sets + above, partial) + + + SuperscriptsandSubscripts (x2070 to x209f) + + + CurrencySymbols (x20a0 to x20b1) + + + LetterlikeSymbols_servicemark (x2120) + + + LetterlikeSymbols_trademark (x2122) + + + LetterlikeSymbols (x2100 to x214b, except for the above two, + partial) + + + NumberForms (x2150 to x218f) + + + Arrows (x2190 to x21ff, partial) + + + MathematicalOperators (x2200 to x22ff, partial) + + + ControlPictures (x2400 to x243f) + + + EnclosedAlphanumerics (x2460 to x24ff) + + + GeometricShapes (x25a0 to x25f7, partial) + + + MiscellaneousSymbols (x2600 to x26ff, partial) + + + Dingbats (x2700 to x27be, partial) + + + AlphabeticPresentationForms (xfb00 to xfb04 only) + + + ArabicPresentationForms-B_wordjoiner (xfeff) + + + + + diff --git a/xsl/params/man.charmap.uri.xml b/xsl/params/man.charmap.uri.xml new file mode 100644 index 000000000..50939dae7 --- /dev/null +++ b/xsl/params/man.charmap.uri.xml @@ -0,0 +1,38 @@ + + +man.charmap.uri +boolean + + +man.charmap.uri +URI for custom roff character map + + + + + + + + +Description + +For converting certain Unicode symbols and special characters in +UTF-8 or UTF-16 encoded XML source to appropriate groff/roff +equivalents in man-page output, the DocBook XSL Stylesheets +distribution includes an XSLT character +map. That character map can be considered the standard roff +character map for the distribution. + +If the value of the man.charmap.uri +parameter is non-empty, that value is used as the URI for the location +for an alternate roff character map to use in place of the standard +roff character map provided in the distribution. + + +Do not set a value for man.charmap.uri +unless you have a custom roff character map that differs from the +standard one provided in the distribution. + + + diff --git a/xsl/params/man.charmap.use.subset.xml b/xsl/params/man.charmap.use.subset.xml new file mode 100644 index 000000000..c9146c96e --- /dev/null +++ b/xsl/params/man.charmap.use.subset.xml @@ -0,0 +1,66 @@ + + +man.charmap.use.subset +boolean + + +man.charmap.use.subset +Use subset of character map instead of full map? + + + + + + + + +Description + +If the value of the +man.charmap.use.subset parameter is non-zero, +a subset of the roff character map is used instead of the full roff +character map. The profile of the subset used is specified by the +man.charmap.subset.profile parameter. + + + You may want to experiment with setting a non-zero value of + man.charmap.use.subset, so that the full + character map is used. Depending on which XSLT engine you run, + setting a non-zero value for + man.charmap.use.subset may significantly + increase the time needed to process your documents. Or it may + not. For example, if you set it and run it with xsltproc, it seems + to dramatically increase processing time; on the other hand, if you + set it and run it with Saxon, it does not seem to increase + processing time significantly + + + +Details +For converting certain Unicode symbols and special characters in +UTF-8 or UTF-16 encoded XML source to appropriate groff/roff +equivalents in man-page output, the DocBook XSL Stylesheets +distribution includes a roff character map that contains more than 800 character +mappings. That character map can be considered the standard roff +character map for the distribution. + + +You can use the man.charmap.uri +parameter to specify a URI for the location for an alternate roff +character map to use in place of the standard roff character map +provided in the distribution. + + +Because it is not terrifically efficient to use the standard +800-character character map in full -- and for most (or all) users, +never necessary to use it in full -- the DocBook XSL Stylesheets +support a mechanism for using, within any given character map, a +subset of character mappings instead of the full set. You can use the +man.charmap.subset.profile parameter to tune +the profile of that subset to use. + + + + diff --git a/xsl/params/man.hyphenate.xml b/xsl/params/man.hyphenate.xml new file mode 100644 index 000000000..665b503b6 --- /dev/null +++ b/xsl/params/man.hyphenate.xml @@ -0,0 +1,21 @@ + + +man.hyphenate + + + +man.hyphenate +Specifies hyphenation behavior for man-page output + + + +false + + +Description + +If the value of this parameter is true, words +may be hyphenated in man output. Otherwise, they may not. + + + diff --git a/xsl/params/man.output.encoding.xml b/xsl/params/man.output.encoding.xml new file mode 100644 index 000000000..d98ed86c2 --- /dev/null +++ b/xsl/params/man.output.encoding.xml @@ -0,0 +1,23 @@ + + +man.output.encoding +string + + +man.output.encoding +Encoding used for man-page output + + + + + + + +Description + +This parameter specifies the encoding to use for files generated +by the manpages stylesheet. Not all processors support specification +of this parameter. + + + diff --git a/xsl/params/man.output.quietly.xml b/xsl/params/man.output.quietly.xml new file mode 100644 index 000000000..5232f1108 --- /dev/null +++ b/xsl/params/man.output.quietly.xml @@ -0,0 +1,25 @@ + + +man.output.quietly + + + +man.output.quietly +Suppress filename messages emitted when generating output? + + + + + + + + +Description + +If zero (the default), for each man-page file created, a message +with the name of the file is emitted. If non-zero, the files are +output "quietly" -- that is, the filename messages are +suppressed. + + +