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

[Jeffrey Fearn]

Ruediger Landmann wrote:
> 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:

I don't think the supplied examples are very useful.

The first example are two are products, and are no different than how it 
currently works.

The second example compares a product and a brand, they are not 
equivalent. If you do the mental exercise required to make them 
equivalent, you either get to the product structure we currently use, or 
you get in to a divisive hell you will no doubt regret soon enough.

> 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?

How do you layout 6 levels so the levels are obvious without having a 
ridiculous level of indentation?

Given the space restriction, how do you layout more than two levels 
without running in to serious line wrapping issues?

You need to supply a layout of how this would work.

> 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, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY