qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajith Attapattu <rajit...@gmail.com>
Subject Re: Website update 4
Date Fri, 24 May 2013 13:28:19 GMT
On Fri, May 24, 2013 at 8:56 AM, Justin Ross <justin.ross@gmail.com> wrote:

> On Fri, May 24, 2013 at 8:37 AM, Rob Godfrey >> Sort of.  In general,
> for release content, there's a special
> >> generation step.  That's really a per-release task, however, not
> >> something that many developers would typically do.  The idea is that
> >> the release manager would do the generation with each new release.
> >> I've spent a good deal of time to make this easy (much easier than
> >> it's been in the past), probably because it's one of the jobs I've had
> >> to do with each release.
> >>
> >> Also, I guess I should say that the two steps are easily collapsed:
> >> "make gen-release RELEASE=0.22 render".
> >>
> >> Trunk documentation would, as you suggest, best be solved by automated
> >> builds.
> >>
> >>
> > So I'm at a bit of a loss as to why a two step document generation
> process
> > would be a good idea.  Is there something that is now being done that
> > cannot be done using the docbook -> html XSL transforms?  I'm not the
> > greatest fan of docbook, but adding in a secondary transform on top of an
> > existing transform seems a little odd.  If docbook cannot give us the
> > output we need, why are we still using docbook?
>
> Agreed about docbook; I'm not a fan, and I'd love to move away from it.
>

Markdown is a more friendly (and less clunky format) and the doc is
readable on it's own.
There ware ways to convert docbook to Markdown. So maybe we should look at
that option.

What do u think ?


>
> It's more like an import step.  The docbook content is (sensibly)
> maintained under the main qpid source tree.  The web content is
> (sensibly) maintained under the website source.  On the website, we
> fuse the two together for the release docs, mating the website
> template (with its navigation) to the body html from docbook.  Indeed,
> I favor removing the site template stuff from the docbook scripts
> under the qpid source tree.  I currently scrub it out.
>
> There's another less important reason.  Docbook generates lousy html,
> so I sanitize it (to xhtml) to make things like link checking work
> nicely.
>
> Justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message