[publican-list] RFC -- Menu subheadings for Publican-driven websites

[Ruediger Landmann]

On 05/05/2010 01:43 PM, Darrin Mison wrote:
> On 05/05/2010, at 12:15 PM, Ruediger Landmann wrote:
>
>    
>> I've been trying out the web publishing features in Publican 1.99 and it's all working very very nicely so far. It certainly makes managing a library of documentation a lot less onerous and time-consuming :)
>>
>> The automatically generated menus are one of the biggest time-and-effort savers in Publican 1.99; but I wonder if they could be a little more flexible?
>>
>> At the moment (within each language) documents are grouped by product, then version number. However, some documents might not be tied to a specific version of a product. For example, in Fedora, we have documentation for the operating system itself, which is clearly version-specific; documentation for various other software included in Fedora (like SELinux) which is also version-specific; and then we have contributor documentation like the "Translation Quick Start Guide" which is not version specific at all.
>>
>> Instead of having to tie these to a product version, it would be nice to group these as "All versions" or "Not version specific" or perhaps no subheading at all?
>>
>> I guess the danger is that enabling such a feature would be a license for people to fill such a directory with all kinds of cruft -- I think that forcing writers to think in terms of "to which version of which product does this document really apply?" has been a Good Thing in Publican so far.
>>
>> Therefore, I wonder what people here think is the best way to handle genuinely non-version-specific content in a documentation library?
>>      
> Optional configuration to override of the menu generation would be handy for these situations where more flexibility is required.  Perhaps on a book by book basis ?
>
> Personally I'm thinking about the idea of being able to group different products together under higher level headings would be handy, eg KDE&  GNOME or RHEL&  JBoss.
>
>    

So how about something like this as a mechanism, to draw these two ideas 
together:

In a document's cfg file, you could set:

web_group_1 (defaults to product)
web_group_2 (defaults to product version)
web_group_3 (defaults to -1)
...
web_group_6 (defaults to -1)

Six levels of nesting should be enough for anybody, right?

Setting any of these parameters to "-1" would mean that it (and any 
web_groups underneath it) are not used. Therefore, by default, the menu 
would work exactly as it does now, but if people publishing docs prefer, 
they could set arbitrary groupings of docs, or even turn off groups 
entirely (by setting web_group_1: -1)

In the Fedora example I used earlier, I'd change the "product" in the 
Translation Quick Start Guide to "Contributor Documentation" and  set 
web_group_2: -1 in the publican.cfg file.

Cheers
Rudi