[publican-list] RFC -- Menu subheadings for Publican-driven websites
Jeffrey Fearn
jfearn at redhat.com
Thu May 13 05:55:27 UTC 2010
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
More information about the publican-list
mailing list