Re: [Boost-docs] [quickbook] Breaking a line

Subject: Re: [Boost-docs] [quickbook] Breaking a line
From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2011-01-25 16:04:33

On Tue, Jan 25, 2011 at 10:57 PM, Edward Diener <eldiener_at_[hidden]> wrote:
> On 1/25/2011 9:12 AM, Dean Michael Berris wrote:
>>
>> For all intents and purposes as well as practically-speaking (and
>> without drudging up the "no tables" and "structure/presentation" split
>> debates that have already concerned the web standards guys for the
>> past couple of decades already) I think this should be considered. It
>> seems to be easier to mold the tools around users than it is to try to
>> change user behavior. ;)
>
> If a user can not present a document in a layout he prefers, then there is
> something wrong with the tools that produce that document, whether it is
> docbook, css, fop, or whatever that produces that final document in whatever
> forms ( html, pdf etc. ) are available.

Well... I don't necessarily agree that there's something "wrong"
there. We aren't actually working with a single word processor here.

> Changing human behavior to not care
> about the layout of a document is just stupid to me. It is tantamount to an
> author of a book saying to the publisher "Here is the text of my book. Put
> it together any way you like just so the reader can read the words
> consecutively with the punctuation provided."

I don't know much about writing books -- I always thought authors
largely didn't concern themselves with the layout of a book unless it
was a comic book or a children's book (and I'm positive different
kinds of authors use different kinds of tools) -- but I do know a bit
about dealing with technologies that the web browsers deal with (in
this case HTML and CSS).

In the early days of HTML people thought it was alright to have <br>,
<font>, and other layout elements like <pre> and <table> to be made
part of the markup language. Unfortunately browsers didn't deal with
these elements the same way so the clever guys that came up with CSS
allowed for web authors to write with just the semantic structure of
the document in mind and let the designers (and the browser) deal with
a standard presentation language for defining the presentation of the
data. The hope is (and is largely seen today) that the document model
will somehow convey semantic information for humans and machines to be
able to "understand" what the document structure is -- for javascript
to be able to deal with the DOM, for CSS styles to be applied to
elements in the DOM, and for programmatic application of
transformations in the case of XML and XSLT.

>From the web design/development perspective it's perfectly natural to
separate the concerns of layout from semantic structure -- it helps
with search engine optimization, allows for a single style sheet to
apply to a variety of pages, convey "rich" information about the
document being presented, etc. -- but if you had to write both the
HTML/CSS by hand, then it is a pain. Fortunately things like WYSIWG
editors make that largely transparent to you and the better ones even
have a clean split between the structure and the presentation.

Unfortunately for us people who have to deal with different types of
output, the easiest thing that could possibly work (and the one that
would make it as easily extensible and maintainable) is to agree to
write in a common format. For Boost it seems that the preferred
toolchain is Quickbook+Doxygen->Boostbook->PDF/HTML+CSS.

FWIW there should be a way to define an XSLT transform for a certain
Boostbook tag to use the appropriate HTML+CSS combo for properly
displaying a "broken line" without having to use the <br/> tag in
HTML. I just don't know enough Boostbook to be able to do that though.

-- 
Dean Michael Berris
about.me/deanberris