Local document customizations

[James Laska]

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 

-- 
==========================================
 James Laska         -- jlaska(a)redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================

[Tommy Reynolds]

Uttered James Laska <jlaska(a)redhat.com&gt;, 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

[James Laska]

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

-- 
==========================================
 James Laska         -- jlaska(a)redhat.com
 Quality Engineering -- Red Hat, Inc.
==========================================

[Tommy Reynolds]

Uttered James Laska <jlaska(a)redhat.com&gt;, 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