docbook-apps

Dear All,

as promised, I've published a demo output
https://www.bilyujezd.cz/beta/strucna-historie.html

Core changes against the current WebHelp:
- responsive design (Mobile First)
- breadcrumb
- improved ToC processing (ToC is linked, not embedded in every HTML file)
- enhanced search related code (cleaning up the code for better maintenance)
- enhanced translation support (all messages are stored in standard l10n XML
files)
- storing client state even on file system or localhost (utilizing HTML5
Local Storage)
- removing jQuery and jQueryUI dependency

Further features:
- ability to enlarge downsized images (aka lightbox, especially useful for
SVG images)
- ability to copy links to specific anchors
- SASS styling (interpreted into CSS)

Weaknesses:
- only modern browsers are supported (Chrome, FF, Edge, IE10+)
- no custom params to override current bahavior
- no out-of-the-box scripts for copying dependencies to the target
destination


Should I put related XSL files and resources to my GitHub account or
directly to some DocBook sandbox?

Thanks,

Jan

Hi Jan and all,

that looks really nice and more modern than what we have recently, and
should be more flexible too from what I read.

Hope to see it soon on github.

Cheers,

Camille

Le 16/04/2017 à 16:46, Jan Tosovsky a écrit :
> Dear All,
>
> as promised, I've published a demo output
> https://www.bilyujezd.cz/beta/strucna-historie.html
>
> Core changes against the current WebHelp:
> - responsive design (Mobile First)
> - breadcrumb
> - improved ToC processing (ToC is linked, not embedded in every HTML file)
> - enhanced search related code (cleaning up the code for better maintenance)
> - enhanced translation support (all messages are stored in standard l10n XML
> files)
> - storing client state even on file system or localhost (utilizing HTML5
> Local Storage)
> - removing jQuery and jQueryUI dependency
>
> Further features:
> - ability to enlarge downsized images (aka lightbox, especially useful for
> SVG images)
> - ability to copy links to specific anchors
> - SASS styling (interpreted into CSS)
>
> Weaknesses:
> - only modern browsers are supported (Chrome, FF, Edge, IE10+)
> - no custom params to override current bahavior
> - no out-of-the-box scripts for copying dependencies to the target
> destination
>
>
> Should I put related XSL files and resources to my GitHub account or
> directly to some DocBook sandbox?
>
> Thanks,
>
> Jan
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>

On 4/16/17 9:46 AM, Jan Tosovsky wrote:
> as promised, I've published a demo output
> https://www.bilyujezd.cz/beta/strucna-historie.html

Wow, that looks great! It was in need of a refresh. Frontend stuff grows
stale quickly.

> Weaknesses:
> - only modern browsers are supported (Chrome, FF, Edge, IE10+)

That's not a weakness ;-)

...

> - no out-of-the-box scripts for copying dependencies to the target
> destination

It was always tricky to maintain those. Everybody needs something
different and there's no clean "customization layer" mechanism like with
xslt. It is nice to provide something that 'just works out of the box',
and at least something that builds sample output as a test for each
build though.

> Should I put related XSL files and resources to my GitHub account or
> directly to some DocBook sandbox?

I'm sure if you do a PR, others will jump in and help you finish the
integration. It sounds like the format still meets a need for several users.

Regards,
David

On Tue, Apr 18, 2017 at 2:19 PM, David Cramer <david@thingbag.net> wrote:

> On 4/16/17 9:46 AM, Jan Tosovsky wrote:
> > as promised, I've published a demo output
> > https://www.bilyujezd.cz/beta/strucna-historie.html
>
>
Impressive UX Jan. Please do send a PR to [1] itself.

I'm curious on how you achieved not embedding ToC on every page. Can you
shed some light?

[1] https://github.com/docbook/xslt10-stylesheets

Thanks,
KasunG


> Wow, that looks great! It was in need of a refresh. Frontend stuff grows
> stale quickly.
>
> > Weaknesses:
> > - only modern browsers are supported (Chrome, FF, Edge, IE10+)
>
> That's not a weakness ;-)
>
> ...
>
> > - no out-of-the-box scripts for copying dependencies to the target
> > destination
>
> It was always tricky to maintain those. Everybody needs something
> different and there's no clean "customization layer" mechanism like with
> xslt. It is nice to provide something that 'just works out of the box',
> and at least something that builds sample output as a test for each
> build though.
>
> > Should I put related XSL files and resources to my GitHub account or
> > directly to some DocBook sandbox?
>
> I'm sure if you do a PR, others will jump in and help you finish the
> integration. It sounds like the format still meets a need for several
> users.
>
> Regards,
> David
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>


--
~~~*******'''''''''''''*******~~~
*Kasun Gajasinghe*
Senior Software Engineer; WSO2 Inc.; http://wso2.com,
*Linked-in: *http://lk.linkedin.com/in/gajasinghe
*Blog: **http://blog.kasunbg.org* <http://blog.kasunbg.org/>


*GitHub: **http://github.com/kasunbg* <http://github.com/kasunbg>

Thank you all for your positive feedback!

It is the best motivation for me. I am quite busy with other activities, but I'll try to move this further later next month.

Some answers:

> I notice you're using <simplesect>. Have you tried your XSL with

structuring?

Sure, the section element is the first class citizen.

> I'm especially interested to see if this could be adapted
> to provide features (search, side navigation, etc) to
> other tools that can only output HTML out of box.

Not sure what is meant by other tools. To enable this functionality (using provided scripts) your HTML structure should match the original one (mine). Do those tools support generating outputs in a customized structure?

> I'm curious on how you achieved not embedding ToC on every page.

Indeed, there is no XInclude analogy in HTML :-(

On top of that, you cannot access/manipulate local files via JavaScript (i.e. read HTML snippet in one file and put it into a dedicated DIV in your file).

However, if your content is static and structured, it can be provided in the form of JavaScript object (JSON) and thus linked (e.g. in the HTML header) like other JavaScript files. Once loaded, that object is accessible like any other global variable. In my customization the nested object structure is iterated/converted into HTML's

• elements with proper CSS classes. The JSON is same for all pages. The current menu item is highlighted dynamically via script.
  
  In one huge document (2000 PDF pages) the embedded ToC itself represented ca 2 MB! In every page. The rest of file size was between 10-600 kB, the total package size was ca 150 MB. Loading pages was so sloow.
  
  While the browser has to load the similar size now (just split into two parts), it is much faster as that separate ToC (JSON) can be cached and reused for other pages.
  
  Jan