Hi folks,
Some of our process documents can become somewhat large, which lends well to the chunked html output. Taking that a step further we've found it helpful to have 2 toc settings where the main table of contents only goes one level deep (chapter). Once you click on a chapter you then see the detailed toc for that section. This has received some good mileage and seems break up a document into manageable chunks.
To see an example of the output see http://people.redhat.com/~jlaska/documentation-guide-en/ . Curious what folks think about this, is there a way to allow doc writers to make this customization without modifying main-html.xsl?
Thanks, James
Uttered James Laska jlaska@redhat.com, spake thus:
Some of our process documents can become somewhat large, which lends well to the chunked html output. Taking that a step further we've found it helpful to have 2 toc settings where the main table of contents only goes one level deep (chapter). Once you click on a chapter you then see the detailed toc for that section. This has received some good mileage and seems break up a document into manageable chunks.
Both the document ToC and the chapter ToC seems to share a common setting "doc.section.depth", so they can't be set independantly. However, since a chapter is a level down inside the document, a 1-level deep ToC there does provide a bit more detail that was hidden in the document ToC.
Curious what folks think about this, is there a way to allow doc writers to make this customization without modifying main-html.xsl?
I can add this capability to the "docs-common" infrastructure if the consensus is to do this.
My question is this: do we want document authors to have that much control over the rendering, or is this a more project-level choice?
Cheers
On Fri, 2005-10-28 at 10:18 -0500, Tommy Reynolds wrote:
My question is this: do we want document authors to have that much control over the rendering, or is this a more project-level choice?
Excellent question, and I'm not sure of the answer.
I added some local customizations (trying to yank them out now to get in sync with fdp) that allowed doc authors to pass in xsltproc --param and --stringparam values (via the document Makefile). This allowed for local changes to the toc depth, or even adding glossary.collection generation. It's nice because it acts as an "opt-in" type service, and is not required for basic documentation building.
-James
Uttered James Laska jlaska@redhat.com, spake thus:
My question is this: do we want document authors to have that much control over the rendering, or is this a more project-level choice?
Excellent question, and I'm not sure of the answer.
My hesitation here is that whatever rendering an author does locally is completely irrelavant to the final rendering done by the project before publication. In fact, we reserve the right to use whatever stylesheet we like, even one the authors have never seen, do whatever render styling is appropriate for the media and circumstances.
So, I can add infrastructure to let an author provide additional stylesheet snippets, or paramter settings, but all must realize their efforts will be ignored in the final product. That's why I thought this question needing escalating to the entire project.
Cheers
docs@lists.stg.fedoraproject.org
-
James Laska -
Tommy Reynolds