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 <[email protected]>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY
_______________________________________________
publican-list mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/publican-list
Wiki: https://fedorahosted.org/publican
