[hibernate-dev] Publishing documentation as rendered by asciidoc

[Guillaume SCHEIBEL]

Hi Sanne,

I'll have a look on firefox as well and continue to work on the header.
About the command [1], I just recompile the stylesheets, copy it and run
the asciidoctor command.
In the current build, values for placeholders like {hibernateVersion} are
coming from the pom since I neither have used the pom file nor forced a
value (using -a parameter) you can still see them.

But when you are writing the documentation you don't (most of the time)
need to have all the placeholder values and for ones you do, you can force
a value (CLI parameter or just forcing them at the beginning of the doc).

I'll try the stylesheet with asciidoctor-pdf to see how it goes.

Cheers,
Guillaume

[1] https://gist.github.com/gscheibel/840f163c9d80eeab5a81

On 9 October 2014 12:01, Sanne Grinovero <sanne at hibernate.org> wrote:

> hi Guillaume, great progress!
> In Google's Chrome it looks almost ok, not quite as the headers we
> have on the docs published at [1] but I guess you can easily fix that.
> On Firefox, it looks odd. There is something being repeated all over
> along the whole document.. I hope you can see the same, or let me know
> if I should send you a screenshot?
>
> On the speed: I'm very interested what command you use as that would
> be helpful when writing docs; but I see it didn't apply replacements
> such as {hibernateVersion} and similar. Is that a tradeoff we have to
> pay for quick previews, or can you trick it somehow?
>
> thanks a lot for your help,
> Sanne
>
>
> On 8 October 2014 19:09, Guillaume SCHEIBEL
> <guillaume.scheibel at gmail.com> wrote:
> > Hi there,
> >
> > Here [1] is the first draft of the HSearch documentation.
> > I've just worked on the background image (the gradient at the top) and
> the
> > title / banner.
> >
> > Let me know your thoughts.
> >
> >
> > BTW, to generate the CSS file and build the documentation (HTML5 single
> > page) it takes:
> >
> > real 0m1.584s
> > user 0m1.073s
> > sys 0m0.220s
> >
> > So pretty fast ins't it.
> >
> > Cheers
> > Guillaume
> >
> > [1]
> >
> https://www.dropbox.com/s/tzp90mvtbpuirhg/hibernate%20search%20doc.zip?dl=0
> >
> > On 7 October 2014 19:33, Sanne Grinovero <sanne at hibernate.org> wrote:
> >>
> >> I think I like the "asciidoctor" theme the best, particularly the
> >> fonts, but I guess it's quite irrelevant considering the aim for
> >> Steve's point 2#.
> >>
> >> On 7 October 2014 19:15, Guillaume SCHEIBEL
> >> <guillaume.scheibel at gmail.com> wrote:
> >> > I would go with Foundation but I'd like to have your opinion on that
> >> > guys
> >> >
> >> > On 7 October 2014 19:14, Guillaume SCHEIBEL
> >> > <guillaume.scheibel at gmail.com>
> >> > wrote:
> >> >>
> >> >> I agree with you Steve #1 is the best option.
> >> >> Which asciidoctor theme do you think is the best to use as a "model"
> >> >> for
> >> >> the Hibernate Style sheet (http://themes.asciidoctor.org/preview/) ?
> >> >>
> >> >> On 7 October 2014 19:09, Steve Ebersole <steve at hibernate.org> wrote:
> >> >>>
> >> >>> IMO, the most important thing is the banners.  In terms of most
> >> >>> everything else we generally run into disagreements (rendering
> >> >>> back-ticked
> >> >>> words, e.g.).  I guess I see 2 options:
> >> >>> 1) Start from the simplest.  Just account for the top banner (the
> >> >>> images
> >> >>> mainly).  From there work on the individual pieces as (if) they come
> >> >>> up.
> >> >>> 2) Start with the assumption of making the asciidoc(tor) output look
> >> >>> *exactly* the same as the docbook output.
> >> >>>
> >> >>> Personally I prefer #1 for quite a few reasons
> >> >>>
> >> >>>
> >> >>> On Tue, Oct 7, 2014 at 1:01 PM, Guillaume SCHEIBEL
> >> >>> <guillaume.scheibel at gmail.com> wrote:
> >> >>>>
> >> >>>> Hey,
> >> >>>>
> >> >>>> I've spoken with Sanne and it can be done by using the asciidoctor
> >> >>>> stylesheet-factory.
> >> >>>> I'll try to create a first draft. Any specific requirements other
> >> >>>> than
> >> >>>> it
> >> >>>> should look exactly the same ?
> >> >>>>
> >> >>>> Cheers,
> >> >>>> Guillaume
> >> >>>>
> >> >>>> On 7 October 2014 18:26, Sanne Grinovero <sanne at hibernate.org>
> wrote:
> >> >>>>
> >> >>>> > Hi all,
> >> >>>> > I would love to publish the documentation the way it looks like
> >> >>>> > from
> >> >>>> > the asciidoc rendering (before the transformations via docbook),
> as
> >> >>>> > it
> >> >>>> > looks like much more readable.
> >> >>>> >
> >> >>>> > But I'd like to keep our style and branding rather than the
> default
> >> >>>> > docbook template; did someone already experiment with that? Or
> >> >>>> > could
> >> >>>> > anyone volunteer please as my design skills are better avoided
> :-)
> >> >>>> >
> >> >>>> > Cheers,
> >> >>>> > Sanne
> >> >>>> > _______________________________________________
> >> >>>> > hibernate-dev mailing list
> >> >>>> > hibernate-dev at lists.jboss.org
> >> >>>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >> >>>> >
> >> >>>> _______________________________________________
> >> >>>> hibernate-dev mailing list
> >> >>>> hibernate-dev at lists.jboss.org
> >> >>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >> >>>
> >> >>>
> >> >>
> >> >
> >
> >
>