You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Brian Denny <br...@briandenny.net> on 2003/11/08 17:36:37 UTC
[PATCH] Re: Suggestion for book TOC: one level deeper
[Reposting with PATCH in the subject line. I'd commit this but would
prefer a +1 from a book author first.]
On Thu, Nov 06, 2003 at 11:01:01AM -0600, B. W. Fitzpatrick wrote:
> "Schrom.Brian" <Br...@IGT.com> writes:
> >
> > Use the toc.section.depth parameter to indicate how many levels of section
> > titles should appear in the TOCs. If you set it to a value of 3, for
> > example, then TOCs will include up to sect3 titles. The default value is 2.
>
> Well, the problem is that all the subcommands are 'refentry's and not
> 'sect3's... Is there anything that will help there? Or do we have to
> wrap every refentry in a sect3?
I did some testing... toc.section.depth doesn't appear to help.
Setting generate.section.toc.level to 2, though, causes section-specific
TOCs to appear under the headings for individual sections -- and in this
case, a TOC for the refentries does appear under "svn Subcommands",
although it still doesn't appear in the main TOC.
Try the following patch and see if you like the result. (Make sure to
observe that TOCs now appear under *all* sect1 and sect2 headers.)
The patch is also attached, in case of mailer line-wrapping.
Log:
Add section-specific TOCs under individual section headers.
Index: doc/book/Makefile
===================================================================
--- doc/book/Makefile (revision 7659)
+++ doc/book/Makefile (working copy)
@@ -37,8 +37,8 @@
RUN_FOP = ${BOOK_TOP}/tools/bin/run-fop.sh
# Book xsltproc options for HTML output
-BOOK_HTML_XSLTPROC_OPTS = --stringparam html.stylesheet styles.css
-BOOK_CHUNK_HTML_XSLTPROC_OPTS = stringparam html.stylesheet styles.css
+BOOK_HTML_XSLTPROC_OPTS = --stringparam html.stylesheet styles.css --stringparam generate.section.toc.level 2
+BOOK_CHUNK_HTML_XSLTPROC_OPTS = stringparam html.stylesheet styles.css --stringparam generate.section.toc.level 2
# Book xsltproc options for PDF and PostScript output
# BOOK_PDF_XSLTPROC_OPTS = --stringparam page.height 9in --stringparam page.width 6.4in
Re: Another book suggestion: an index, or an appendix of magic properties
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On Nov 14, 2003, at 8:30 PM, Eric Hanchrow wrote:
>
> I'm constantly forgetting the proper spelling of certain magic
> properties -- is it "svn:eol-style" or "svn:eolstyle"; and are the
> magic values "native", "unix", or what? It'd be nice if there were
> an index in which I could look up "properties", or at least (yet)
> another appendix with all the magic properties.
How about the output of 'svn help pset'? It seems to contain what
you're looking for.
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Another book suggestion: an index, or an appendix of magic properties
Posted by "B. W. Fitzpatrick" <fi...@red-bean.com>.
"John R. Daily" <jo...@geekhavoc.com> writes:
> At (time_t)758021483 Eric Hanchrow wrote:
>
> > ...It'd be nice if there were
> > an index in which I could look up "properties", or at least (yet)
> > another appendix with all the magic properties.
>
> Seems like a good time to ask: are there any plans for an index?
>
> Certainly it's a tedious task to add the markup, but the DocBook
> stylesheets I've used in the past do a nice job generating an
> index.
AFAIK, O'Reilly will do the indexing footwork for us, and we'll have to
integrate it back into our tree when they're done.
-Fitz
--
Brian W. Fitzpatrick <fi...@red-bean.com> http://www.red-bean.com/fitz/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Another book suggestion: an index, or an appendix of magic properties
Posted by "John R. Daily" <jo...@geekhavoc.com>.
At (time_t)758021483 Eric Hanchrow wrote:
> ...It'd be nice if there were
> an index in which I could look up "properties", or at least (yet)
> another appendix with all the magic properties.
Seems like a good time to ask: are there any plans for an index?
Certainly it's a tedious task to add the markup, but the DocBook
stylesheets I've used in the past do a nice job generating an
index.
-John
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Another book suggestion: an index, or an appendix of magic
properties
Posted by Eric Hanchrow <of...@blarg.net>.
I'm constantly forgetting the proper spelling of certain magic
properties -- is it "svn:eol-style" or "svn:eolstyle"; and are the
magic values "native", "unix", or what? It'd be nice if there were
an index in which I could look up "properties", or at least (yet)
another appendix with all the magic properties.
As it stands now, I point my browser to
http://svnbook.red-bean.com/book.html (600 Kb) and just search.
--
The whole point of loud music is to make it possible
to date without talking.
-- Roger Ebert
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: New [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by Brian Denny <br...@briandenny.net>.
On Fri, Nov 14, 2003 at 09:49:03AM -0500, mark benedetto king wrote:
> > following patch, which I think does exactly what we want. (If we added
> > refentrys elsewhere that we *didn't* want to appear in the TOC, then we
> > would have to rethink this approach.) Opinions?
>
> +1
>
> This approach satisfies my earlier concerns (with the same caveat
> about future refentrys that you state above).
Committed in r7756.
-brian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: New [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by mark benedetto king <mb...@lowlatency.com>.
On Thu, Nov 13, 2003 at 10:28:49PM -0800, Brian Denny wrote:
> On Tue, Nov 11, 2003 at 07:34:28PM -0800, Brian Denny wrote:
> > My patch merely sets an XSL customization property that is already
> > defined by the existing docbook-xsl stylesheets. However, it is
> > possible to define an XSL customization layer that overrides entire
> > XSL templates. I am 99% sure that it is possible to get what we want
> > this way, without touching the XML. It's just a question of how (and
> > how much work). If I knew more XSL I probably would have done it
> > already. Maybe I'll look into it some more.
>
> Okay, I looked into it some more. Revision 7740 paved the way for the
> following patch, which I think does exactly what we want. (If we added
> refentrys elsewhere that we *didn't* want to appear in the TOC, then we
> would have to rethink this approach.) Opinions?
+1
This approach satisfies my earlier concerns (with the same caveat
about future refentrys that you state above).
--ben
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
New [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by Brian Denny <br...@briandenny.net>.
On Tue, Nov 11, 2003 at 07:34:28PM -0800, Brian Denny wrote:
> My patch merely sets an XSL customization property that is already
> defined by the existing docbook-xsl stylesheets. However, it is
> possible to define an XSL customization layer that overrides entire
> XSL templates. I am 99% sure that it is possible to get what we want
> this way, without touching the XML. It's just a question of how (and
> how much work). If I knew more XSL I probably would have done it
> already. Maybe I'll look into it some more.
Okay, I looked into it some more. Revision 7740 paved the way for the
following patch, which I think does exactly what we want. (If we added
refentrys elsewhere that we *didn't* want to appear in the TOC, then we
would have to rethink this approach.) Opinions?
Log:
Customize the book's HTML stylesheets so that <refentry> elements
which are children of <sect1> or <sect2> elements are represented
in the Table of Contents.
Index: doc/book/tools/html-stylesheet.xsl
===================================================================
--- doc/book/tools/html-stylesheet.xsl (revision 7740)
+++ doc/book/tools/html-stylesheet.xsl (working copy)
@@ -3,5 +3,26 @@
<xsl:import href="xsl/html/docbook.xsl"/>
<xsl:param name="html.stylesheet">styles.css</xsl:param>
+ <xsl:param name="toc.section.depth">3</xsl:param>
+ <xsl:param name="annotate.toc">0</xsl:param>
+ <xsl:template match="sect1" mode="toc">
+ <xsl:param name="toc-context" select="."/>
+ <xsl:call-template name="subtoc">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ <xsl:with-param name="nodes"
+ select="sect2|refentry|bridgehead[$bridgehead.in.toc != 0]"/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template match="sect2" mode="toc">
+ <xsl:param name="toc-context" select="."/>
+
+ <xsl:call-template name="subtoc">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ <xsl:with-param name="nodes"
+ select="sect3|refentry|bridgehead[$bridgehead.in.toc != 0]"/>
+ </xsl:call-template>
+ </xsl:template>
+
</xsl:stylesheet>
Index: doc/book/tools/chunk-stylesheet.xsl
===================================================================
--- doc/book/tools/chunk-stylesheet.xsl (revision 7740)
+++ doc/book/tools/chunk-stylesheet.xsl (working copy)
@@ -3,5 +3,26 @@
<xsl:import href="xsl/html/chunk.xsl"/>
<xsl:param name="html.stylesheet">styles.css</xsl:param>
+ <xsl:param name="toc.section.depth">3</xsl:param>
+ <xsl:param name="annotate.toc">0</xsl:param>
+ <xsl:template match="sect1" mode="toc">
+ <xsl:param name="toc-context" select="."/>
+ <xsl:call-template name="subtoc">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ <xsl:with-param name="nodes"
+ select="sect2|refentry|bridgehead[$bridgehead.in.toc != 0]"/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template match="sect2" mode="toc">
+ <xsl:param name="toc-context" select="."/>
+
+ <xsl:call-template name="subtoc">
+ <xsl:with-param name="toc-context" select="$toc-context"/>
+ <xsl:with-param name="nodes"
+ select="sect3|refentry|bridgehead[$bridgehead.in.toc != 0]"/>
+ </xsl:call-template>
+ </xsl:template>
+
</xsl:stylesheet>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by mark benedetto king <mb...@lowlatency.com>.
On Wed, Nov 12, 2003 at 07:46:08AM -0800, Brian Denny wrote:
> On Wed, Nov 12, 2003 at 09:11:27AM -0500, mark benedetto king wrote:
> > On Tue, Nov 11, 2003 at 07:34:28PM -0800, Brian Denny wrote:
> > >
> > > My patch merely sets an XSL customization property that is already
> > > defined by the existing docbook-xsl stylesheets. However, it is
> > > possible to define an XSL customization layer that overrides entire
> > > XSL templates. I am 99% sure that it is possible to get what we want
> > > this way, without touching the XML. It's just a question of how (and
> > > how much work). If I knew more XSL I probably would have done it
> > > already. Maybe I'll look into it some more.
> > >
> >
> > Right, so it gets applied across the board; what is desired is exceptional
> > behaviour.
>
> Is it? Would a rule "show <refentry> items in the main TOC" have
> undesirable effects? I.e., are there other <refentry> items which we
> *don't* want to show up?
>
Hmm. It looks like there aren't any others, at all, right now.
What else would we want to use <refentry> for? The other cmdline
tools?
--ben
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by Brian Denny <br...@briandenny.net>.
On Wed, Nov 12, 2003 at 09:11:27AM -0500, mark benedetto king wrote:
> On Tue, Nov 11, 2003 at 07:34:28PM -0800, Brian Denny wrote:
> >
> > My patch merely sets an XSL customization property that is already
> > defined by the existing docbook-xsl stylesheets. However, it is
> > possible to define an XSL customization layer that overrides entire
> > XSL templates. I am 99% sure that it is possible to get what we want
> > this way, without touching the XML. It's just a question of how (and
> > how much work). If I knew more XSL I probably would have done it
> > already. Maybe I'll look into it some more.
> >
>
> Right, so it gets applied across the board; what is desired is exceptional
> behaviour.
Is it? Would a rule "show <refentry> items in the main TOC" have
undesirable effects? I.e., are there other <refentry> items which we
*don't* want to show up?
It's true that the most straightforward path to getting what we want in
this case would just be to wrap the <refentry> elements in
<sect3></sect3>. I am more than happy to do this, if it's acceptable
from a "what o'reilly needs from us" standpoint.
-brian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by mark benedetto king <mb...@lowlatency.com>.
On Tue, Nov 11, 2003 at 07:34:28PM -0800, Brian Denny wrote:
>
> My patch merely sets an XSL customization property that is already
> defined by the existing docbook-xsl stylesheets. However, it is
> possible to define an XSL customization layer that overrides entire
> XSL templates. I am 99% sure that it is possible to get what we want
> this way, without touching the XML. It's just a question of how (and
> how much work). If I knew more XSL I probably would have done it
> already. Maybe I'll look into it some more.
>
Right, so it gets applied across the board; what is desired is exceptional
behaviour. It seems to me that the easiest way to get that exceptional
behaviour is to change the XML to be, well, exceptional.
--ben
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by Brian Denny <br...@briandenny.net>.
On Wed, Nov 12, 2003 at 01:39:50AM +0000, Julian Foad wrote:
> Brian Denny wrote:
> >[Reposting with PATCH in the subject line. I'd commit this but would
> >prefer a +1 from a book author first.]
>
> I want a table of contents that lists each svn command individually.
Yeah, me too.
> Your patch puts tables of contents in subsections as well as at the
> beginning of each chapter, and this seems to force the generation of a
> table of svn commands as a side effect, but I do not much like having so
> many tables of contents.
Right.
> could be displayed in a more visible style, which might be achieved by
> making it a <sect3> or whatever. I would prefer that, if there is some way
> that that can be done while remaining compatible with O'Reilly's rules.
> Maybe O'Reilly is aware of the problem and has a work-around or updated
> rules.
My assumption is that O'Reilly has their own XSL stylesheets and/or
tools to convert the XML into whatever form they use for their books.
It follows that we can make any customizations we want at the XSL layer
just so long as we don't go fiddling with the XML. (That's not to say
that we couldn't potentially wrap the <refentry>s in <sect3>s, I don't
know about that).
My patch merely sets an XSL customization property that is already
defined by the existing docbook-xsl stylesheets. However, it is
possible to define an XSL customization layer that overrides entire
XSL templates. I am 99% sure that it is possible to get what we want
this way, without touching the XML. It's just a question of how (and
how much work). If I knew more XSL I probably would have done it
already. Maybe I'll look into it some more.
-brian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Re: Suggestion for book TOC: one level deeper
Posted by Julian Foad <ju...@btopenworld.com>.
Brian Denny wrote:
> [Reposting with PATCH in the subject line. I'd commit this but would
> prefer a +1 from a book author first.]
I want a table of contents that lists each svn command individually.
Your patch puts tables of contents in subsections as well as at the beginning of each chapter, and this seems to force the generation of a table of svn commands as a side effect, but I do not much like having so many tables of contents.
So my vote is +0 for this patch.
The problem is that it is hard to find a particular subcommand. One reason for this is the lack of a table of contents for them, and another is that the name of each subcommand is displayed as normal text, although the word "Name" is in a large font. It would be better if the actual command name could be displayed in a more visible style, which might be achieved by making it a <sect3> or whatever. I would prefer that, if there is some way that that can be done while remaining compatible with O'Reilly's rules. Maybe O'Reilly is aware of the problem and has a work-around or updated rules.
- Julian
> On Thu, Nov 06, 2003 at 11:01:01AM -0600, B. W. Fitzpatrick wrote:
>
>>"Schrom.Brian" <Br...@IGT.com> writes:
>>
>>>Use the toc.section.depth parameter to indicate how many levels of section
>>>titles should appear in the TOCs. If you set it to a value of 3, for
>>>example, then TOCs will include up to sect3 titles. The default value is 2.
>>
>>Well, the problem is that all the subcommands are 'refentry's and not
>>'sect3's... Is there anything that will help there? Or do we have to
>>wrap every refentry in a sect3?
>
> I did some testing... toc.section.depth doesn't appear to help.
>
> Setting generate.section.toc.level to 2, though, causes section-specific
> TOCs to appear under the headings for individual sections -- and in this
> case, a TOC for the refentries does appear under "svn Subcommands",
> although it still doesn't appear in the main TOC.
>
> Try the following patch and see if you like the result. (Make sure to
> observe that TOCs now appear under *all* sect1 and sect2 headers.)
> Log:
> Add section-specific TOCs under individual section headers.
>
> Index: doc/book/Makefile
> ===================================================================
> --- doc/book/Makefile (revision 7659)
> +++ doc/book/Makefile (working copy)
> @@ -37,8 +37,8 @@
> RUN_FOP = ${BOOK_TOP}/tools/bin/run-fop.sh
>
> # Book xsltproc options for HTML output
> -BOOK_HTML_XSLTPROC_OPTS = --stringparam html.stylesheet styles.css
> -BOOK_CHUNK_HTML_XSLTPROC_OPTS = stringparam html.stylesheet styles.css
> +BOOK_HTML_XSLTPROC_OPTS = --stringparam html.stylesheet styles.css --stringparam generate.section.toc.level 2
> +BOOK_CHUNK_HTML_XSLTPROC_OPTS = stringparam html.stylesheet styles.css --stringparam generate.section.toc.level 2
I see that this second variable is not used, so I have just deleted it.
>
> # Book xsltproc options for PDF and PostScript output
> # BOOK_PDF_XSLTPROC_OPTS = --stringparam page.height 9in --stringparam page.width 6.4in
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org