From: Michael S. <xm...@us...> - 2005-06-28 18:39:32
|
Update of /cvsroot/docbook/xsl/manpages In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9854/manpages Modified Files: docbook.xsl synop.xsl param.xweb param.ent Log Message: 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. Index: docbook.xsl =================================================================== RCS file: /cvsroot/docbook/xsl/manpages/docbook.xsl,v retrieving revision 1.38 retrieving revision 1.39 diff -u -U2 -r1.38 -r1.39 --- docbook.xsl 27 Jun 2005 10:56:02 -0000 1.38 +++ docbook.xsl 28 Jun 2005 18:39:20 -0000 1.39 @@ -113,7 +113,11 @@ <!-- * $manpage.contents so that we can manipluate them further. --> <xsl:variable name="manpage.contents"> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <!-- * top.comment = commented-out section at top of roff source --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <xsl:call-template name="top.comment"/> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <!-- * TH.title.line = title line in header/footer of man page --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <xsl:call-template name="TH.title.line"> <!-- * .TH "TITLE" "SECTION" "extra1" "extra2" "extra3" --> @@ -135,7 +139,25 @@ <xsl:with-param name="extra3" select="$metadata/othermetadata"/> </xsl:call-template> - <!-- * main body of man page --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <!-- * Now deal with setting default hyphenation and justification --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <!-- * --> + <!-- * If the value of man.hypenate is zero (the default), then --> + <!-- * disable hyphenation (".nh" means "no hyphenation", I guess) --> + <xsl:if test="$man.hyphenate = 0"> + <xsl:text>.nh </xsl:text> + </xsl:if> + <!-- * If the value of man.justify is zero (the default), then --> + <!-- * disable justification (".ad l" means "adjust to left only" --> + <xsl:if test="$man.justify = 0"> + <xsl:text>.ad l </xsl:text> + </xsl:if> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <!-- * Main body of man page --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <xsl:apply-templates/> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <!-- * AUTHOR section (at end of man page) --> + <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <xsl:call-template name="author.section"> <xsl:with-param name="info" select="$info"/> Index: synop.xsl =================================================================== RCS file: /cvsroot/docbook/xsl/manpages/synop.xsl,v retrieving revision 1.17 retrieving revision 1.18 diff -u -U2 -r1.17 -r1.18 --- synop.xsl 26 Jun 2005 07:10:38 -0000 1.17 +++ synop.xsl 28 Jun 2005 18:39:20 -0000 1.18 @@ -115,6 +115,12 @@ <xsl:template match="cmdsynopsis"> - <xsl:text>.ad l </xsl:text> - <xsl:text>.hy 0 </xsl:text> + <!-- * if justification is enabled by default, turn it off temporarily --> + <xsl:if test="$man.justify != 0"> + <xsl:text>.ad l </xsl:text> + </xsl:if> + <!-- * if hyphenation is enabled by default, turn it off temporarily --> + <xsl:if test="$man.hyphenate != 0"> + <xsl:text>.hy 0 </xsl:text> + </xsl:if> <xsl:text>.HP </xsl:text> <xsl:value-of select="string-length (normalize-space (command)) + 1"/> @@ -122,6 +128,12 @@ <xsl:apply-templates/> <xsl:text> </xsl:text> - <xsl:text>.ad </xsl:text> - <xsl:text>.hy </xsl:text> + <!-- * if justification is enabled by default, turn it back on --> + <xsl:if test="$man.justify != 0"> + <xsl:text>.ad </xsl:text> + </xsl:if> + <!-- * if hyphenation is enabled by default, turn it back on --> + <xsl:if test="$man.hyphenate != 0"> + <xsl:text>.hy </xsl:text> + </xsl:if> </xsl:template> @@ -137,9 +149,21 @@ <!-- * line breaks only occur between separate paramdefs. --> <xsl:template match="funcsynopsis"> - <xsl:text>.ad l </xsl:text> - <xsl:text>.hy 0 </xsl:text> - <xsl:apply-templates/> - <xsl:text>.ad </xsl:text> - <xsl:text>.hy </xsl:text> + <!-- * if justification is enabled by default, turn it off temporarily --> + <xsl:if test="$man.justify != 0"> + <xsl:text>.ad l </xsl:text> + </xsl:if> + <!-- * if hyphenation is enabled by default, turn it off temporarily --> + <xsl:if test="$man.hyphenate != 0"> + <xsl:text>.hy 0 </xsl:text> + </xsl:if> + <xsl:apply-templates/> + <!-- * if justification is enabled by default, turn it back on --> + <xsl:if test="$man.justify != 0"> + <xsl:text>.ad </xsl:text> + </xsl:if> + <!-- * if hyphenation is enabled by default, turn it back on --> + <xsl:if test="$man.hyphenate != 0"> + <xsl:text>.hy </xsl:text> + </xsl:if> </xsl:template> Index: param.xweb =================================================================== RCS file: /cvsroot/docbook/xsl/manpages/param.xweb,v retrieving revision 1.4 retrieving revision 1.5 diff -u -U2 -r1.4 -r1.5 --- param.xweb 27 Jun 2005 10:11:11 -0000 1.4 +++ param.xweb 28 Jun 2005 18:39:21 -0000 1.5 @@ -20,5 +20,5 @@ </bookinfo> - <preface> + <preface id="preface"> <title>Introduction</title> @@ -31,5 +31,5 @@ <reference id="general"> <title>General</title> -&man.alignment; +&man.justify; &man.hyphenate; &man.output.quietly; @@ -44,5 +44,5 @@ &man.charmap.subset.profile; </reference> - <appendix> + <appendix id="stylesheet"> <title>The Stylesheet</title> @@ -67,5 +67,5 @@ ******************************************************************** --> -<src:fragref linkend="man.alignment.frag"/> +<src:fragref linkend="man.justify.frag"/> <src:fragref linkend="man.hyphenate.frag"/> <src:fragref linkend="man.output.quietly.frag"/> Index: param.ent =================================================================== RCS file: /cvsroot/docbook/xsl/manpages/param.ent,v retrieving revision 1.3 retrieving revision 1.4 diff -u -U2 -r1.3 -r1.4 --- param.ent 27 Jun 2005 10:56:02 -0000 1.3 +++ param.ent 28 Jun 2005 18:39:21 -0000 1.4 @@ -1,4 +1,4 @@ <!ENTITY man.hyphenate SYSTEM "../params/man.hyphenate.xml"> -<!ENTITY man.alignment SYSTEM "../params/man.alignment.xml"> +<!ENTITY man.justify SYSTEM "../params/man.justify.xml"> <!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml"> <!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml"> |