[publican-list] Formatting Articles, a discussion of BZ #494147

[Jeffrey Fearn]

Ruediger Landmann wrote:
> On 12/02/2009 03:39 PM, Jeffrey Fearn wrote:
>> Hi, I have been giving some thought to the issues around the 
>> formatting of articles vs books, and thought I'd poll the list for input.
>>
>> The question of layout seems to depend on what the fundamental 
>> difference between a book and an article is. The answer appears to be 
>> not much.
>>
> 
>  From a writing point of view, the fundamental difference seems to be 
> one of scope; an article is typically narrow in focus, and generally 
> "shorter" than a book (yes, I know, "how long is a piece of string?")
> 
>  From a publishing point of view, I think the key difference is that an 
> article is often not published by itself, but as part of a longer work 
> like a magazine, journal, or book; which is where (for example), I think 
> that the difference in how Publican formats books and articles in PDF is 
> useful.

The difference you are talking about is user controlled content and not 
formatting, there is almost no difference in the way the same content is 
formatted.

> Questions of layout aside, the default structure produced by Publican 
> for books (including our lengthy "Document Conventions" section) I think 
> overwhelms a short piece of writing, like a "How To", which is the kind 
> of thing I've used <article> for up to now, for example:
> 
> http://docs.fedoraproject.org/readme-live-image/en-US.html
> 
> http://docs.fedoraproject.org/readme-burning-isos/en-US.html
> 
> Of course, I know that the same effect can be generated by overriding 
> the defaults (and you'll notice that in those two examples, I actually 
> /added/ the Feedback section, which is not there by default in articles...)

Try adding the rest of the common content to your article, or removing 
it from a book, and you will see their are only minor style changes, 
like a missing HR, or slightly different formatting on a title, etc.

The change is so small there is no justification for having both these 
tags, after all the only change required to a book would be commenting 
out an xi:include or two.

>> If this is the case there is no need to have a layout that varies more 
>> than required by the minimal structural differences between a book and 
>> an article then.
>>
>> So, as a base, an article should look pretty much like a book ... but 
>> why bother having articles at all then?
>>
>> Because there are special types of articles that could look different!
>>
>> Article has an attribute, class, which can contain the following values:
>>
>> * NULL
>> * faq
>> * journalarticle
>> * productsheet
>> * specification
>> * techreport
>> * whitepaper
>>
>> Now these things may be worth styling differently, perhaps much 
>> differently, than a book.
>>
> 
> I agree; this has useful possibilities, because, like you say, some of 
> these (say, FAQ) might have practically no resemblance to a book at all...
> 
>> Maybe journalarticle should be dual column?
> 
> And maybe somehow inherit the "parentbook" attribute if it's being built 
> as part of a <book> and display this somewhere on the page?

You need to build the garden before you plant the flowers!

>>
>> Perhaps a whitepaper should have extra wide margins for people to 
>> scribble in?
>>
>> A special cover page for a productsheet perchance?
> 
> Or be laid out in landscape, designed to be folded in half?
 >
> I'm sure other people here have other ideas about what we could do with 
> those specific formats...

But will they actually post about them or wait until we make decisions 
and then bitch endlessly that they didn't get to have any input?

Cheers, Jeff.

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