Feat. Req. — Side TOC Expansion by Context #27
Comments
|
HI, sorry about the delayed response. I have always been thinking that I should improve the empty page at the beginning of the part as this sample. One way to improve it is to make the part page more authentic as printed document such as placing the part title on the two third of the page and put the footnote bar at the bottom of the viewport. I am planning to introduce the theme support in the future. Another way is that the author should write some paragraphs to introduce the part. But it is understandable some people just want a tool to fill the space with TOC. So I should support this feature as an option too.
You have been requesting feature for TOCs not only for every top level such as asciidoctor-multipage but also every chapter. And on top of that, you want the full expanded TOC page. I was wondering if you are thinking about the layout without a TOC sidebar. If we have a TOC on the sidebar I don't see any reasons to include the full TOC page separately. Regarding to the expansion of TOC items on the sidebar, I am also planning to support it with themes. It can control more fine-grained way. Currently, I would like to make the output look like the followings with themes.
|
From what I seen in real-use scenarios (especially in the DocBook format) is that often author add to the Part page a dedicated TOC for the Part contents.
Maybe I should expand a bit more on the actual contexts I'm using the chunker for. I mostly create chunked books for HTML executable eBooks and CHM Help (both Windows only formats). Depending on the actual publication, I might use a different exeBook compiler. In any case, I currently need to further process the HTML pages generated by the chunker in order to adapt them to the project. Some exeBook compilers provide their own TOC sidebar, which the user can toggle on and off, in this case having a sidebar TOC in the HTML page is redundant, since the application TOC bar can be hidden when not needed, allowing to view the contents full width; also, this side TOC is independent of the page, so it doesn't scroll with the contents. (when I use this feature, I scrape the sidebar away from the generated HTML files). But in general (website or eBook alike), when dealing with very big multi-part documents, the sidebar can become too long (especially if it's always unfolded), and in very short page (e.g. Part pages, Appendices, etc.) the risk is that the TOC sidebar ends up being many time longer than the actual page contents (which doesn't look nice). Hence my proposal to keep the side-TOC shorter by only expanding the sections of the current Part being shown. The rationale for having a full TOC page (or include it after the Preamble position) is that for big publications with sections up to level 6 the sidebar TOC becomes too cluttered if it shows all levels (usually a max depth of 2 or 3 is more than enough for the sidebar), but having a full-fledged TOC at the beginning of the book is useful when the reader needs to find a specific sub-sections. This is also a practice often used in PDF publications, and sometimes even in printed books, where you have both a short and long TOC. CHM Help files also don't need a sidebar TOC, since CHM features a TOC and Index sidebar, but even with CHM publications it would be useful to have a YOC page (and most CHM books do have one, e.g. O'Leary publications do). For these reasons, I think that it would be desirable to have as much control as possible over the TOC, since different authors might be using the chunker in different contexts, and not all publications are alike. As a side note, it's worth mentioning that CHM Help files, most exeBook compilers, and custom Windows applications, display the HTML contents using the old IE/Trident base WebControl, which has limited HTML5 and CSS3 support, and uses a very old JavaScript engine. In CHM Help documents, the WebControl is always configured to emulate IE7; in exeBooks and Windows applications it's usually executed in IE11 emulation mode. For this reason, in exeBooks and CHM Help publication I also have to scrape the embedded JavaScript added by asciidoctor-chunker to scroll the TOC, because it raises an error in the IE/WebControl. Modern applications and exeBook compilers that use the new Edge/Chromium WebControl 2 don't have this problem, but since the new WebControl is not available on older versions of Windows, I still need to offer end users a version of the eBook targeting the IE/Trident WebControl. I think that for better cross application/domain support it would be better not to embed in the HTML pages any JavaScript or CSS, but keep them all external, so end users can substitute them with alternative scripts working for their application (e.g. in CHM publications it's safer to use JScript, since it's consistently supported across different IE versions). End users can always process the HTML pages with some dedicated tool to embed the external resources, including images which can be converted to DataURI — there's a plethora of command line tools to chose from to handle similar tasks, but removing embedded scripts is not as easy.
Cool. But bear in mind the limitations in HTML5/CSS3/JS support for publications relying on the old IE/Trident WebContol. After all, CHM Help files are still widely used, even though MS tried hard to make them obsolete (without providing any alternative format, though). Even under Win 10, users keep installing the CHM Viewer, and many (if not most) third party Windows applications still provide the documentation in CHM Help format.
They are really neat, especially the OCaml Programming example (elegant minimalist template, with foldable TOC on the side). I like the vertical side bars for navigating previous/next page in the PureScript by Example, they are very practical since they are always at hand (but discreetly so, not invasive at all). The Deep Learning theme seems just a variation of the default AsciiDoc theme, but dark version. I've come across the asciidoctor-skins project, which I believe are CSS themes that can be used as drop-in replacements of the default CSS used by Asciidoctor: https://github.com/darshandsoni/asciidoctor-skins I haven't had a chance to check if they actually work with the latest Asciidoctor version (which I believed changed the generated tags, e.g. using divs instead of tables to centre contents), but if they do work as drop-in replacements, and provided the project is and will be actively maintained in time (ensuring themes are updated if Asciidoctor changes the template tags), then it would be nice if these skins could be integrated into the chunker, allowing users to choose a replacement theme. Unfortunately, the asciidoctor-skins project doesn't use Sass or Less to generate the CSS themes, which would have made further customizations easier. But so far I didn't really find many projects offering alternative themes for the Asciidoctor HTML backend. The original default templates used by Asciidoctor are (or used to be) those found at the stylesheet-factory: https://github.com/asciidoctor/asciidoctor-stylesheet-factory But the project uses a very old version of Foundation, requiring Compass (a long defunct component of the now obsolete Ruby edition of Sass), which is probably why we never saw many third party templates in the first place (Foundation 4 was overtly complicate to work with in the first place). Since I'm starting to need nicer templates for my publications, I might soon start working on my own theme factory using Sass, and possibly some Sass/CSS framework. When (if) I do get something going, I'll be happy to consider asciidoctor-chunker integration in the project. |
|
I understand now the reason for dedicated TOC page. I can implement inserting TOCs into the pages. I think you should be able to suppress the sidebar TOC with Asciidoctor placing a directive in the adoc source. You can also activate the directive conditionally from the command line. Since I am not a good designer and I am not familiar with Sass, your contribution to the themes is very much welcome! |
No-Side TOC via
|
When chunking large books, it might be useful to have an option that will restrict the TOC contents shown on the sidebar to Parts and Chapters, except for the current chapter, for which all its sections and sub-sections should shown. This would make the book easier to navigate, without having to scroll up and down the sidebar. Usually the reader either wants to jump to another section in the current chapter, or to another chapter, so this would allow focusing on the current chapter contents but without loosing touch with the overall parts and chapters structure.
Ideally, various options could allow fine-grain control over the TOC expansion levels — e.g. show only Parts, except for the current Part and Chapter, etc.
I've seen some Asciidoctor alternative templates which simulate this via JavaScript, where the whole TOC is always available but only the current Chapter is expanded, whereas all the others need to be clicked on to expand. But I personally prefer the static solution mentioned above, especially if publishing a book on a website.
Additionally, it might also be useful being able to generate a dedicated TOC page, with the full TOC expanded to every possible level, since it's friendlier to read when the section title are long and get wrapped in the sidebar.
If I've understood correctly, asciidoctor-chunker depends on the Asciidoctor generated TOC in order to reconstruct it (i.e. by parsing it and manipulating it). This also means that it should be possible to generate the HTML file with a full-blown TOC (six levels, or whatever the max level is for any given doc) and then control via asciidoctor-chunker options which level to show in the sidebar TOC — i.e. this would allow having a TOC page with the full TOC, and a sidebar TOC with less levels (e.g. 2 level, Chapter and Sections), where the latter only serves to quickly jump to sections within the current chapter/page, whereas the former allows finding sub-sections, etc.
Obviously, this whole approach might also be affected by the depth specifier value passed by the user, but in general the principle of a navigation-by-chapter TOC should make sense (i.e. as an optional feature).
The text was updated successfully, but these errors were encountered: