modular documents and h[1-6]
Opened this issue · 4 comments
I haven't seen a method to use modular files in htmlbook.
I would like to do
html==> head ==> body ==> section data-src="include file"
(Which is handy if you have to include licenses in your books)
The usage of the body element as start of htmlbook makes it difficult to archive this. Because it use html==>head properties as instructions for the article or book. Once you go modular then what would mean these properties of an include section containing 2 or more chapters?
A solution is needed where
- every (modular) file is a valid html5 document
- every (modular) file is treated the same
making it
Children of Body which are part of htmlbook vocabulary are (possible) valid htmlbook sections.
in file book.html i would write:
html==> head ==> body
- section data-type="book" H1 My book
- section data-src="chapter1.html"
in file chapter1.html
html==> head ==> body
- section data-type="chapter" H1 my Chapter
section data-src="include file" is the xinclude from docbook.
The rule that h[1-6] elements match the depth of the section could be violated in this scenario e.g. you include a modular file type section styled level 2, At level 4. Therefor relaxing the rule to a TITLE is any of the h[1-6] elements seems necessary
Hi @renez19,
HTMLBook doesn't have a custom mechanism for doing includes, because we're operating on the assumption that folks who want to modularize their files will use one of the following standard XHTML/XML mechanisms for doing so:
- Include other files using XIncludes: http://www.w3.org/TR/xinclude/
- Use custom-defined entities: http://www.freebsd.org/doc/en/books/fdp-primer/xml-primer-include.html
With respect to the validity of modular files, the XML Schema for HTMLBook (https://github.com/oreillymedia/HTMLBook/blob/master/schema/htmlbook.xsd) is set up such that you can validate documents that either have <html> as the root element, or have a top-level (chapter, preface, appendix, etc.) <section> element as the root element. So you can indeed put your chapters in separate files and still validate them against the Schema.
Regarding usage of h1-h6 elements with <section> elements, we have no plans to relax the rule that the heading element should match the depth of the section, because we feel this is the best approach semantically. It would be the user's responsibility to ensure that when they included files, the markup in the included files was for the appropriate depth in the source document.
Hope this is helpful,
Sanders
Thanks for your time to respond to my suggestion.
Isn't your answer contradicting the use of html5, html editors and creating invalid html5 documents?
Rene
Sanders Kleinfeld notifications@github.com wrote:
Hi @renez19,
HTMLBook doesn't have a custom mechanism for doing includes, because we're operating on the assumption that folks who want to modularize their files will use one of the following standard XHTML/XML mechanisms for doing so:
Include other files using XIncludes: http://www.w3.org/TR/xinclude/ Use custom-defined entities: http://www.freebsd.org/doc/en/books/fdp-primer/xml-primer-include.html
With respect to the validity of modular files, the XML Schema for HTMLBook (https://github.com/oreillymedia/HTMLBook/blob/master/schema/htmlbook.xsd) is set up such that you can validate documents that either have as the root element, or have a top-level (chapter, preface, appendix, etc.)
element as the root element. So you can indeed put your chapters in separate files and still validate them against the Schema. Regarding usage of h1-h6 elements with
elements, we have no plans to relax the rule that the heading element should match the depth of the section, because we feel this is the best approach semantically. It would be the user's responsibility to ensure that when they included files, the markup in the included files was for the appropriate depth in the source document. Hope this is helpful,
Sanders—
Reply to this email directly or view it on GitHub.
Sure thing! Sorry, I think I may have introduced some semantic confusion around my use of the word "validity".
If you modularize into separate HTML files for chapters with a <section> root, you can validate those files against the HTMLBook schema to confirm whether or not they conform to the HTMLBook specifications for a chapter.
If by "valid", you mean that the HTML document has a root of <html> and contains head/body tags, then, no, the individual chapter files would not be valid.
Does that answer your question? Or perhaps I am still misunderstanding the issue(s) you're raising?
Your summary is correct. My suggestion was to stay within the html5 limits with htmlbook and to keep the number of technologies to one or as close to.
When writing a book with more then 3 chapters you want modular documents. All of those must be valid html5 IMHO.
Thanks for the time you took to answer. Let's agree to disagree.
Rene
Sanders Kleinfeld notifications@github.com wrote:
Sure thing! Sorry, I think I may have introduced some semantic confusion around my use of the word "validity".
If you modularize into separate HTML files for chapters with a
root, you can validate those files against the HTMLBook schema to confirm whether or not they conform to the HTMLBook specifications for a chapter. If by "valid", you mean that the HTML document has a root of and contains head/body tags, then, no, the individual chapter files would not be valid.
Does that answer your question? Or perhaps I am still misunderstanding the issue(s) you're raising?
—
Reply to this email directly or view it on GitHub.