From 7a327452aad2a34010ec91a7143f7db5b1e0641c Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Tue, 28 Jun 2005 18:39:21 +0000 Subject: [PATCH] Support man.justify and man.hyphenate params. (closes #1229225). Note that default for the both of those is zero (off), because justified text looks good only when it is also hyphenated; to quote the "Hypenation" node from the groff info page: Since the odds are not great for finding a set of words, for every output line, which fit nicely on a line without inserting excessive amounts of space between words, `gtroff' hyphenates words so that it can justify lines without inserting too much space between words. The problem is that groff is not particularly smart about how it does hyphenation; it can end up hyphenating a lot of things that you don't want hyphenated (names of symbols, for example), and it is difficult and tiresome work to prevent it from doing that. So, disabling both justification and hyphenation ensures that hyphens won't get inserted where you don't want to them, and you don't end up with lines containing excessive amounts of space between words. Yes, these default settings run counter to how most existing man pages are formatted. But there are some notable exceptions, such as the perl man pages. --- xsl/manpages/docbook.xsl | 24 +++++++++++++++++- xsl/manpages/param.ent | 2 +- xsl/manpages/param.xweb | 8 +++--- xsl/manpages/synop.xsl | 40 ++++++++++++++++++++++++------ xsl/params/man.alignment.xml | 22 ----------------- xsl/params/man.hyphenate.xml | 37 ++++++++++++++++++++++----- xsl/params/man.justify.xml | 48 ++++++++++++++++++++++++++++++++++++ 7 files changed, 139 insertions(+), 42 deletions(-) delete mode 100644 xsl/params/man.alignment.xml create mode 100644 xsl/params/man.justify.xml diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl index 9505e3347..f9e71f600 100644 --- a/xsl/manpages/docbook.xsl +++ b/xsl/manpages/docbook.xsl @@ -112,9 +112,13 @@ + + + + @@ -134,9 +138,27 @@ - + + + + + + + + .nh + + + + + .ad l + + + + + + diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent index e118313e9..bc5f5df96 100644 --- a/xsl/manpages/param.ent +++ b/xsl/manpages/param.ent @@ -1,5 +1,5 @@ - + diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb index a8f166f40..15dedbdce 100644 --- a/xsl/manpages/param.xweb +++ b/xsl/manpages/param.xweb @@ -19,7 +19,7 @@ - + Introduction This is reference documentation for all user-configurable @@ -30,7 +30,7 @@ General -&man.alignment; +&man.justify; &man.hyphenate; &man.output.quietly; &man.output.encoding; @@ -43,7 +43,7 @@ &man.charmap.use.subset; &man.charmap.subset.profile; - + The Stylesheet The param.xsl stylesheet is just a @@ -66,7 +66,7 @@ ******************************************************************** --> - + diff --git a/xsl/manpages/synop.xsl b/xsl/manpages/synop.xsl index 365f3239c..92e59bfd0 100644 --- a/xsl/manpages/synop.xsl +++ b/xsl/manpages/synop.xsl @@ -114,15 +114,27 @@ - .ad l - .hy 0 + + + .ad l + + + + .hy 0 + .HP - .ad - .hy + + + .ad + + + + .hy + @@ -136,11 +148,23 @@ - .ad l - .hy 0 + + + .ad l + + + + .hy 0 + - .ad - .hy + + + .ad + + + + .hy + diff --git a/xsl/params/man.alignment.xml b/xsl/params/man.alignment.xml deleted file mode 100644 index 02a71740c..000000000 --- a/xsl/params/man.alignment.xml +++ /dev/null @@ -1,22 +0,0 @@ - - -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.hyphenate.xml b/xsl/params/man.hyphenate.xml index 665b503b6..318aa6b53 100644 --- a/xsl/params/man.hyphenate.xml +++ b/xsl/params/man.hyphenate.xml @@ -1,21 +1,46 @@ - + man.hyphenate - +boolean man.hyphenate -Specifies hyphenation behavior for man-page output +Enable hyphenation? -false + +0 Description -If the value of this parameter is true, words -may be hyphenated in man output. Otherwise, they may not. +If non-zero, hyphenation is enabled. + + +The default value for this parameter is zero because groff is +not particularly smart about how it does hyphenation; it can end up +hyphenating a lot of things that you don't want hyphenated (names of +symbols, for example), and it is difficult and tiresome work to +prevent it from doing that. + +That said, justified text can look very bad unless you also +hyphenate it; to quote the "Hypenation" node from the groff info page: + +
+ Since the odds are not great for finding a set of + words, for every output line, which fit nicely on a line without + inserting excessive amounts of space between words, `gtroff' + hyphenates words so that it can justify lines without inserting too + much space between words. +
+ +So, if you set a non-zero value for the +man.justify parameter (to enable +justification), then you should probably also set a non-zero value for +man.hyphenate (to enable hyphenation). + + diff --git a/xsl/params/man.justify.xml b/xsl/params/man.justify.xml new file mode 100644 index 000000000..3692dda19 --- /dev/null +++ b/xsl/params/man.justify.xml @@ -0,0 +1,48 @@ + + +man.justify +boolean + + +man.justify +Justify text to both right and left margins? + + + + +0 + + +Description + +If non-zero, text is justified to both the right and left +margins (or, in roff terminology, "adjusted and filled" to both the +right and left margins). If zero (the default), text is adjusted to +the left margin only -- producing what is traditionally called +"ragged-right" text. + + +The default value for this parameter is zero because justified +text looks good only when it is also hyphenated. Without hyphenation, +excessive amounts of space often end up getting between words, in +order to "pad" lines out to align on the right margin. + +The problem is that groff is not particularly smart about how it +does hyphenation; it can end up hyphenating a lot of things that you +don't want hyphenated (names of symbols, for example), and it is +difficult and tiresome work to prevent it from doing that. So, +disabling both justification and hyphenation ensures that hyphens +won't get inserted where you don't want to them, and you don't end up +with lines containing excessive amounts of space between words. + +However, if do you decide to set a non-zero value for the +man.justify parameter (to enable +justification), then you should probably also set a non-zero value for +man.hyphenate (to enable hyphenation). + +Yes, these default settings run counter to how most existing man +pages are formatted. But there are some notable exceptions, such as +the perl man pages. + + + -- 2.49.0