docbook-apps

"Denis Bradford" <denis.bradford@verizon.net> said:

Hello Denis,

> Not sure if this the best place to post this, but here goes:

Where better than here?

> Sina, I'm so glad to see active development on Website, it's such a
> terrific product. As long as you're thinking about its next stage of
> development, has anyone suggested folding Website into DocBook? I use
> both all the time, and I think each has features that could enhance the
> other.
>
> I once implemented a doc set that pulled together a bunch of DocBooks
> and some non-DocBook content using an olink sitemap. I was amazed to
> learn how powerful sitemaps and generated olink databases are. It
> occurred to me that they could be used to do far more than enable
> olinks: they contain all the metadata you need to organize and process a
> whole doc system -- not unlike Website layouts (and ditamaps, for that
> matter). On the company web site we served our doc set as an Eclipse
> infocenter, but I couldn't help thinking how much easier it would have
> been to post it as a Website.
>
> Another example, on the Website side: why should only books and help
> systems have an index? It's a great navigation tool for an informational
> web site, too. So, I hacked the Website stylesheets to generate a
> DocBook index for the site. Not pretty XSL, but my readers love the index.
>
> I realize this is not a trivial thing. Besides the layout, there doesn't
> appear to be much difference between the DocBook and Website (full)
> documents -- mostly a few elements at the top. But the big difference is
> in the processing, and that would no doubt require a lot of work to bridge.
>
> The benefits just might be worth the effort. Making Website a DocBook
> output option, instead of a separate dialect, would increase its value
> for technical documentation -- a low-tech, frameless alternative to
> Eclipse infocenters and HTML-based help browsers.

Some of these features are indeed useful for both DocBook HTML output and DocBook Website but please note the fundamental distinction between DocBook and DocBook Website. DocBook helps format documents and publish them anywhere, including the Web whereas DocBook Website helps publish *websites* on the Web and only on the Web.

That said, DocBook Website can, in theory, support all the features provided by the HTML stylesheets for DocBook but it's important to know that DocBook and DocBook Website do not share a common goal.

SinDoc

On 05/20/2010 11:54 AM, Sina K. Heshmati wrote:
> "Denis Bradford"<denis.bradford@verizon.net> said:
>
>
>> I realize this is not a trivial thing. Besides the layout, there doesn't
>> appear to be much difference between the DocBook and Website (full)
>> documents -- mostly a few elements at the top. But the big difference is
>> in the processing, and that would no doubt require a lot of work to bridge.
>>
>> The benefits just might be worth the effort. Making Website a DocBook
>> output option, instead of a separate dialect, would increase its value
>> for technical documentation -- a low-tech, frameless alternative to
>> Eclipse infocenters and HTML-based help browsers.
>>
> Some of these features are indeed useful for both DocBook HTML output and DocBook Website but please note the fundamental distinction between DocBook and DocBook Website. DocBook helps format documents and publish them anywhere, including the Web whereas DocBook Website helps publish *websites* on the Web and only on the Web.
>

I think things aren't quite as clear-cut as that: As an interesting
use-case, consider Sphinx (http://sphinx.pocoo.org/), which started out
as a "documentation tool". It is based on ReST (with its existing
formatters), but adds superstructure to it.
There, generating a "website" proper is just a side-product (or almost).

Taking this to DocBook, I think it would be nice if DB Website content
could be published into an inter-connected set of (pdf) articles or
somesuch. (Since the stylesheets for individual page content already
exists, I imagine that the only new bits required would be templates
that use the website structure information ("layout" or similar), and
generate appropriate inter-document links from that, as well as other
toplevel things such as an index, TOC, etc.)

But, that's just an idea, and may not fit into this GSoC project. Still,
it's worthwhile thinking of this for some future work.

Thanks,
Stefan

--

...ich hab' noch einen Koffer in Berlin...

Stefan Seefeld wrote:
> On 05/20/2010 11:54 AM, Sina K. Heshmati wrote:
>> "Denis Bradford"<denis.bradford@verizon.net> said:
>>
>>
>>> I realize this is not a trivial thing. Besides the layout, there doesn't
>>> appear to be much difference between the DocBook and Website (full)
>>> documents -- mostly a few elements at the top. But the big difference is
>>> in the processing, and that would no doubt require a lot of work to bridge.
>>>
>>> The benefits just might be worth the effort. Making Website a DocBook
>>> output option, instead of a separate dialect, would increase its value
>>> for technical documentation -- a low-tech, frameless alternative to
>>> Eclipse infocenters and HTML-based help browsers.
>>>
>> Some of these features are indeed useful for both DocBook HTML output and DocBook
>> Website but please note the fundamental distinction between DocBook and DocBook
>> Website. DocBook helps format documents and publish them anywhere, including the
>> Web whereas DocBook Website helps publish *websites* on the Web and only on the
>> Web.
>
> I think things aren't quite as clear-cut as that: As an interesting
> use-case, consider Sphinx (http://sphinx.pocoo.org/), which started out
> as a "documentation tool". It is based on ReST (with its existing
> formatters), but adds superstructure to it.
> There, generating a "website" proper is just a side-product (or almost).

Right. Things might not be as clear-cut but agreeing on a definition helps us determine the scope of the project.

> Taking this to DocBook, I think it would be nice if DB Website content
> could be published into an inter-connected set of (pdf) articles or
> somesuch. (Since the stylesheets for individual page content already
> exists, I imagine that the only new bits required would be templates
> that use the website structure information ("layout" or similar), and
> generate appropriate inter-document links from that, as well as other
> toplevel things such as an index, TOC, etc.)
>
> But, that's just an idea, and may not fit into this GSoC project. Still,
> it's worthwhile thinking of this for some future work.

Thanks for sharing.

SinDoc

Hi Sina, please see my response at the bottom.

Sina K. Heshmati wrote:
> "Denis Bradford" <denis.bradford@verizon.net> said:
>
> Hello Denis,
>
>> Not sure if this the best place to post this, but here goes:
>
> Where better than here?
>
>> Sina, I'm so glad to see active development on Website, it's such a
>> terrific product. As long as you're thinking about its next stage of
>> development, has anyone suggested folding Website into DocBook? I use
>> both all the time, and I think each has features that could enhance the
>> other.
>>
>> I once implemented a doc set that pulled together a bunch of DocBooks
>> and some non-DocBook content using an olink sitemap. I was amazed to
>> learn how powerful sitemaps and generated olink databases are. It
>> occurred to me that they could be used to do far more than enable
>> olinks: they contain all the metadata you need to organize and process a
>> whole doc system -- not unlike Website layouts (and ditamaps, for that
>> matter). On the company web site we served our doc set as an Eclipse
>> infocenter, but I couldn't help thinking how much easier it would have
>> been to post it as a Website.
>>
>> Another example, on the Website side: why should only books and help
>> systems have an index? It's a great navigation tool for an informational
>> web site, too. So, I hacked the Website stylesheets to generate a
>> DocBook index for the site. Not pretty XSL, but my readers love the index.
>>
>> I realize this is not a trivial thing. Besides the layout, there doesn't
>> appear to be much difference between the DocBook and Website (full)
>> documents -- mostly a few elements at the top. But the big difference is
>> in the processing, and that would no doubt require a lot of work to bridge.
>>
>> The benefits just might be worth the effort. Making Website a DocBook
>> output option, instead of a separate dialect, would increase its value
>> for technical documentation -- a low-tech, frameless alternative to
>> Eclipse infocenters and HTML-based help browsers.
>
> Some of these features are indeed useful for both DocBook HTML output and DocBook Website but please note the fundamental distinction between DocBook and DocBook Website. DocBook helps format documents and publish them anywhere, including the Web whereas DocBook Website helps publish *websites* on the Web and only on the Web.

> That said, DocBook Website can, in theory, support all the features provided by the HTML stylesheets for DocBook but it's important to know that DocBook and DocBook Website do not share a common goal.

I don't see how the distinction you draw between DocBook and Website is
fundamental. The DocBook stylesheets for PDF and HTML Help don't
represent different goals, they're just different outputs from a single
source.

That was the point I tried to make in citing my own work experience,
where it would have been useful to publish not only to help and PDF, but
also to collection of web pages, all from the same source.

Of course, if the work is beyond the scope of this GSoC project, I
completely understand.

Thanks,
Denis

>
> SinDoc
>
I guess the distinction you draw between DocBook and Website doesn't
seem fundamental to me.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>

Hello Denis,

Denis Bradford wrote:
> Sina K. Heshmati wrote:
>> "Denis Bradford" <denis.bradford@verizon.net> said:
>>
>>> Sina, I'm so glad to see active development on Website, it's such a
>>> terrific product. As long as you're thinking about its next stage of
>>> development, has anyone suggested folding Website into DocBook? I use
>>> both all the time, and I think each has features that could enhance the
>>> other.
>>>
>>> I once implemented a doc set that pulled together a bunch of DocBooks
>>> and some non-DocBook content using an olink sitemap. I was amazed to
>>> learn how powerful sitemaps and generated olink databases are. It
>>> occurred to me that they could be used to do far more than enable
>>> olinks: they contain all the metadata you need to organize and process a
>>> whole doc system -- not unlike Website layouts (and ditamaps, for that
>>> matter). On the company web site we served our doc set as an Eclipse
>>> infocenter, but I couldn't help thinking how much easier it would have
>>> been to post it as a Website.
>>>
>>> Another example, on the Website side: why should only books and help
>>> systems have an index? It's a great navigation tool for an informational
>>> web site, too. So, I hacked the Website stylesheets to generate a
>>> DocBook index for the site. Not pretty XSL, but my readers love the index.
>>>
>>> I realize this is not a trivial thing. Besides the layout, there doesn't
>>> appear to be much difference between the DocBook and Website (full)
>>> documents -- mostly a few elements at the top. But the big difference is
>>> in the processing, and that would no doubt require a lot of work to bridge.
>>>
>>> The benefits just might be worth the effort. Making Website a DocBook
>>> output option, instead of a separate dialect, would increase its value
>>> for technical documentation -- a low-tech, frameless alternative to
>>> Eclipse infocenters and HTML-based help browsers.
>>
>> Some of these features are indeed useful for both DocBook HTML output and DocBook
>> Website but please note the fundamental distinction between DocBook and DocBook
>> Website. DocBook helps format documents and publish them anywhere, including the
>> Web whereas DocBook Website helps publish *websites* on the Web and only on the
>> Web.
>
>> That said, DocBook Website can, in theory, support all the features provided by
>> the HTML stylesheets for DocBook but it's important to know that DocBook and
>> DocBook Website do not share a common goal.
>
> I don't see how the distinction you draw between DocBook and Website is
> fundamental. The DocBook stylesheets for PDF and HTML Help don't
> represent different goals, they're just different outputs from a single
> source.

True. FO and HTML Help stylesheets transform a single source into different outputs. In an abstract way, they are even equivalent. Now, are DocBook Website stylesheets equivalent to FO and HTML Help stylesheets? No, because the source is different.

> That was the point I tried to make in citing my own work experience,
> where it would have been useful to publish not only to help and PDF, but
> also to collection of web pages, all from the same source.

What you mean is a program, X that transforms a DocBook document into a collection of webpages, right? DocBook Website can then process those generated webpages. I never meant to imply that X would not be useful but should X be part of DocBook Website?

> Of course, if the work is beyond the scope of this GSoC project, I
> completely understand.

It is obviously a nice feature to have but it has more to do with DocBook XSL stylesheets than DocBook Website stylesheets.

SinDoc

On Fri, 21 May 2010, Sina K. Heshmati wrote:
> Hello Denis,
>
> Denis Bradford wrote:

> >> "Denis Bradford" <denis.bradford@verizon.net> said:
> >>> The benefits just might be worth the effort. Making Website a DocBook
> >>> output option, instead of a separate dialect, would increase its value
> >>> for technical documentation -- a low-tech, frameless alternative to
> >>> Eclipse infocenters and HTML-based help browsers.

> > Sina K. Heshmati wrote:
> >> Some of these features are indeed useful for both DocBook HTML output
> >> and DocBook Website but please note the fundamental distinction between
> >> DocBook and DocBook Website. DocBook helps format documents and publish
> >> them anywhere, including the Web whereas DocBook Website helps publish
> >> *websites* on the Web and only on the Web.
> >>
> >> That said, DocBook Website can, in theory, support all the features
> >> provided by the HTML stylesheets for DocBook but it's important to know
> >> that DocBook and DocBook Website do not share a common goal.

> Denis Bradford wrote:
> > I don't see how the distinction you draw between DocBook and Website is
> > fundamental. The DocBook stylesheets for PDF and HTML Help don't
> > represent different goals, they're just different outputs from a single
> > source.
>
> True. FO and HTML Help stylesheets transform a single source into different
> outputs. In an abstract way, they are even equivalent. Now, are DocBook
> Website stylesheets equivalent to FO and HTML Help stylesheets? No, because
> the source is different.
>
> > That was the point I tried to make in citing my own work experience,
> > where it would have been useful to publish not only to help and PDF, but
> > also to collection of web pages, all from the same source.
>
> What you mean is a program, X that transforms a DocBook document into a
> collection of webpages, right? DocBook Website can then process those
> generated webpages.

Most immediate issue I can see is that you then have to generate a
layout.xml sitemap that contains hierarchically layed out entries for
every chunked node of any embedded documents and which is automatically
updated as they evolve and are rebuilt. So you need a "meta-layout.xml"
file that knows how those documents are chunked (and which directories
they are in).
That and replacing the headers and footers of the chunks.

When the chunking to html is part of the same website generation process,
then the layout machinary can work it out for itself. I would have to
say that it took me six months to achieve this effect with tabular-toc.
It was not a trivial thing. IIRC I had to write a customisation
for the DocBook HTML chunking layer, as well as modifying a good deal
of Website itself.

> I never meant to imply that X would not be useful but
> should X be part of DocBook Website?

dunno