There's no configuration option for this. I could change pandoc's
behavior if there were a good reason to do so. What are the
differences
between <sect1> etc. and <section>? Why do you need one rather than
the
other?
John
On Jan 4, 11:06 am, "Nicholas C. Zakas" <nicholas.c.za...@gmail.com>
wrote:
From my [admittedly limited] understanding, <sect1> indicates the
canonical outermost section, <sect2> can only appear in <sect1> and
indicates subsections.
My personal preference would be to just use <section>, however,
O'Reilly requires books to be written using the <sect1> and associated
elements instead.
I think it would be really useful to have a configuration option for
this.
-N
On Jan 4, 11:48 am, fiddlosopher <fiddlosop...@gmail.com> wrote:
> There's no configuration option for this. I could change pandoc's
> behavior if there were a good reason to do so. What are the
> differences
> between <sect1> etc. and <section>? Why do you need one rather than
> the
> other?
> John
> On Jan 4, 11:06 am, "Nicholas C. Zakas" <nicholas.c.za...@gmail.com>
> wrote:
> > Hi,
> > Is there a way to tell Pandoc to use <sect1>, <sect2>, etc. for
> > DocBook format instead of <section>?
Section <http://docbook.org/tdg/en/html/section.html>s may be more convenient than numbered sections in some authoring environments because they can be moved around in the document hierarchy without renaming.
As O'Reilly is the 800 lb gorilla in DocBook usage, it would be very useful for Pandoc to support its specs as a general goal; this will IMO be increasingly valuable as ora continues to "open up" various elements of its very sophisticated in-house processes and toolchains.
I don't have any problem changing from <section> to <sectN> tags in the docbook writer, if that would be more useful to the people who use it. If anyone has objections, speak up now!
> I believe the SectX tags are actually more widely used than Section. > From the "definitive guide" at docbook.org:
> There are three types of sectioning elements in DocBook:
> * Explicitly numbered sections, [1]Sect1…[2]Sect5, which must be > properly nested and can only be five levels deep. > * Recursive [3]Sections, which are an alternative to the numbered > sections and have unbounded depth. > * [4]SimpleSects, which are terminal. [5]SimpleSects can occur as the > “leaf” sections in either recursive sections or any of the numbered > sections, or directly in components.
> [6]Sections may be more convenient than numbered sections in some > authoring environments because they can be moved around in the document > hierarchy without renaming. > As O'Reilly is the 800 lb gorilla in DocBook usage, it would be very > useful for Pandoc to support its specs as a general goal; this will IMO > be increasingly valuable as ora continues to "open up" various elements > of its very sophisticated in-house processes and toolchains.
> -- > You received this message because you are subscribed to the Google > Groups "pandoc-discuss" group. > To view this discussion on the web visit > [7]https://groups.google.com/d/msg/pandoc-discuss/-/1Le_5QhwL8UJ. > To post to this group, send email to pandoc-discuss@googlegroups.com. > To unsubscribe from this group, send email to > pandoc-discuss+unsubscribe@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/pandoc-discuss?hl=en.
John MacFarlane <fiddlosop...@gmail.com> wrote: >I don't have any problem changing from <section> to <sectN> tags >in the docbook writer, if that would be more useful to the people >who use it. If anyone has objections, speak up now!
>John
>+++ HansBKK [Jan 04 12 19:22 ]: >> I believe the SectX tags are actually more widely used than Section. >> From the "definitive guide" at docbook.org:
>> There are three types of sectioning elements in DocBook:
>> * Explicitly numbered sections, [1]Sect1…[2]Sect5, which must be >> properly nested and can only be five levels deep. >> * Recursive [3]Sections, which are an alternative to the numbered >> sections and have unbounded depth. >> * [4]SimpleSects, which are terminal. [5]SimpleSects can occur as the >> “leaf” sections in either recursive sections or any of the numbered >> sections, or directly in components.
>> [6]Sections may be more convenient than numbered sections in some >> authoring environments because they can be moved around in the document >> hierarchy without renaming. >> As O'Reilly is the 800 lb gorilla in DocBook usage, it would be very >> useful for Pandoc to support its specs as a general goal; this will IMO >> be increasingly valuable as ora continues to "open up" various elements >> of its very sophisticated in-house processes and toolchains.
>> -- >> You received this message because you are subscribed to the Google >> Groups "pandoc-discuss" group. >> To view this discussion on the web visit >> [7]https://groups.google.com/d/msg/pandoc-discuss/-/1Le_5QhwL8UJ. >> To post to this group, send email to pandoc-discuss@googlegroups.com. >> To unsubscribe from this group, send email to >> pandoc-discuss+unsubscribe@googlegroups.com. >> For more options, visit this group at >> http://groups.google.com/group/pandoc-discuss?hl=en.
>-- >You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. >To post to this group, send email to pandoc-discuss@googlegroups.com. >To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. >For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
>+++ Miek Gieben [Jan 05 12 21:59 ]: >> I object. Because of the max. depth of 5, which isn't there when using section.
>> Sent from my Android device
>> John MacFarlane <fiddlosop...@gmail.com> wrote:
>> >I don't have any problem changing from <section> to <sectN> tags >> >in the docbook writer, if that would be more useful to the people >> >who use it. If anyone has objections, speak up now!
>> >John
>> >+++ HansBKK [Jan 04 12 19:22 ]: >> >> I believe the SectX tags are actually more widely used than Section. >> >> From the "definitive guide" at docbook.org:
>> >> There are three types of sectioning elements in DocBook:
>> >> * Explicitly numbered sections, [1]Sect1…[2]Sect5, which must be >> >> properly nested and can only be five levels deep. >> >> * Recursive [3]Sections, which are an alternative to the numbered >> >> sections and have unbounded depth. >> >> * [4]SimpleSects, which are terminal. [5]SimpleSects can occur as the >> >> “leaf” sections in either recursive sections or any of the numbered >> >> sections, or directly in components.
>> >> [6]Sections may be more convenient than numbered sections in some >> >> authoring environments because they can be moved around in the document >> >> hierarchy without renaming. >> >> As O'Reilly is the 800 lb gorilla in DocBook usage, it would be very >> >> useful for Pandoc to support its specs as a general goal; this will IMO >> >> be increasingly valuable as ora continues to "open up" various elements >> >> of its very sophisticated in-house processes and toolchains.
>> >> -- >> >> You received this message because you are subscribed to the Google >> >> Groups "pandoc-discuss" group. >> >> To view this discussion on the web visit >> >> [7]https://groups.google.com/d/msg/pandoc-discuss/-/1Le_5QhwL8UJ. >> >> To post to this group, send email to pandoc-discuss@googlegroups.com. >> >> To unsubscribe from this group, send email to >> >> pandoc-discuss+unsubscribe@googlegroups.com. >> >> For more options, visit this group at >> >> http://groups.google.com/group/pandoc-discuss?hl=en.
>> >-- >> >You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. >> >To post to this group, send email to pandoc-discuss@googlegroups.com. >> >To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. >> >For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
>> -- >> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. >> To post to this group, send email to pandoc-discuss@googlegroups.com. >> To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. >> For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
>-- >You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. >To post to this group, send email to pandoc-discuss@googlegroups.com. >To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. >For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
> >I don't have any problem changing from <section> to <sectN> tags > >in the docbook writer, if that would be more useful to the people > >who use it. If anyone has objections, speak up now!
> >John
> >+++ HansBKK [Jan 04 12 19:22 ]: > >> I believe the SectX tags are actually more widely used than Section. > >> From the "definitive guide" at docbook.org:
> >> There are three types of sectioning elements in DocBook:
> >> * Explicitly numbered sections, [1]Sect1…[2]Sect5, which must be > >> properly nested and can only be five levels deep. > >> * Recursive [3]Sections, which are an alternative to the numbered > >> sections and have unbounded depth. > >> * [4]SimpleSects, which are terminal. [5]SimpleSects can occur as the > >> “leaf” sections in either recursive sections or any of the numbered > >> sections, or directly in components.
> >> [6]Sections may be more convenient than numbered sections in some > >> authoring environments because they can be moved around in the document > >> hierarchy without renaming. > >> As O'Reilly is the 800 lb gorilla in DocBook usage, it would be very > >> useful for Pandoc to support its specs as a general goal; this will IMO > >> be increasingly valuable as ora continues to "open up" various elements > >> of its very sophisticated in-house processes and toolchains.
> >> -- > >> You received this message because you are subscribed to the Google > >> Groups "pandoc-discuss" group. > >> To view this discussion on the web visit > >> [7]https://groups.google.com/d/msg/pandoc-discuss/-/1Le_5QhwL8UJ. > >> To post to this group, send email to pandoc-discuss@googlegroups.com. > >> To unsubscribe from this group, send email to > >> pandoc-discuss+unsubscribe@googlegroups.com. > >> For more options, visit this group at > >> http://groups.google.com/group/pandoc-discuss?hl=en.
> >-- > >You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. > >To post to this group, send email to pandoc-discuss@googlegroups.com. > >To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. > >For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
> -- > You received this message because you are subscribed to the Google Groups "pandoc-discuss" group. > To post to this group, send email to pandoc-discuss@googlegroups.com. > To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com. > For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
> I still don't see why the original problem can't be solved with a little bit of xlst?
It could. But that is not by itself an argument against making the change. After all, your consideration cuts both ways: <sectN> tags can be changed into <section> tags by xslt too -- or more simply with
| sed -e 's/<sect[0-9]/<section/g'
If use of <sectN> tags is more standard/normal/preferred, then I think it would be better for pandoc to use them. I'm asking for input partly because I don't use docbook myself. Several people are using pandoc to write for O'Reilly, and for them <sectN> would be better.
> +++ Miek Gieben [Jan 05 12 23:00 ]: > > I still don't see why the original problem can't be solved with a little > bit of xlst?
> It could. But that is not by itself an argument against making the > change. After all, your consideration cuts both ways: <sectN> tags can > be changed into <section> tags by xslt too -- or more simply with
> | sed -e 's/<sect[0-9]/<section/g'
> If use of <sectN> tags is more standard/normal/preferred, then I think > it would be better for pandoc to use them. I'm asking for input > partly because I don't use docbook myself. Several people are using > pandoc to write for O'Reilly, and for them <sectN> would be better.
> John
I used to use docbook a long time again. <section> was introduced as an improvement over sectN, and it was recommended for all to switch, i seem to remember. So changing from section to sectN is a move in the wrong direction, i think.
If it's actually very easy to take care of this with an external transform then I guess it's not worth the trouble to give an option, but for me I haven't got the hang of xslt at all yet, and it's non-triviality is IMO a good example of the central reason behind the existence of tools like pandoc and asciidoc.
[ Quoting <hans...@gmail.com> at 23:05 on Jan 5 in "Re: Use of <sect1> i..." ]
> the hang of xslt at all yet, and it's non-triviality is IMO a good example of > the central reason behind the existence of tools like pandoc and asciidoc.
Sorry for mailing twice.
This xslt transforms from <section> to <sect1> and was the most difficult to create:
I didn't want to start a war about which format is better. I'd be
quite happy if there was a CLI option that allows me to opt into using
<sectN> instead of <section>.
-N
On Jan 6, 2:55 am, Miek Gieben <m...@miek.nl> wrote:
> [ Quoting <hans...@gmail.com> at 23:05 on Jan 5 in "Re: Use of <sect1> i..." ]
> > the hang of xslt at all yet, and it's non-triviality is IMO a good example of
> > the central reason behind the existence of tools like pandoc and asciidoc.
> Sorry for mailing twice.
> This xslt transforms from <section> to <sect1> and was the most difficult
> to create:
On Friday, January 6, 2012 5:55:00 PM UTC+7, Miek Gieben wrote:
> [ Quoting <han...@gmail.com> at 23:05 on Jan 5 in "Re: Use of <sect1> > i..." ] > > the hang of xslt at all yet, and it's non-triviality is IMO a good > example of > > the central reason behind the existence of tools like pandoc and > asciidoc.
> Sorry for mailing twice.
> This xslt transforms from <section> to <sect1> and was the most difficult > to create:
> I didn't want to start a war about which format is better. I'd be > quite happy if there was a CLI option that allows me to opt into using > <sectN> instead of <section>.
Pandoc already has so many command-line options; I'd rather not introduce new ones unless it's necessary. Given the ease of translating from one section format to the other, I don't see that a new option is warranted. That's why I posed the question as an either-or.
On Jan 6, 5:45 pm, John MacFarlane <fiddlosop...@gmail.com> wrote:
> +++ Nicholas C. Zakas [Jan 06 12 11:40 ]:
> > I didn't want to start a war about which format is better. I'd be
> > quite happy if there was a CLI option that allows me to opt into using
> > <sectN> instead of <section>.
> Pandoc already has so many command-line options; I'd rather not
> introduce new ones unless it's necessary. Given the ease of translating
> from one section format to the other, I don't see that a new option is
> warranted. That's why I posed the question as an either-or.
The numbered section approach is the legacy approach, and is a
consequence of technical limitations of DTD technology that the RELAX
NG does not have [1]. I believe at one time, DB 5 had dropped support
for numbered sections, in fact.
For that reason, I tend to lean towards preferring the current
behavior.
On Jan 6, 5:45 pm, John MacFarlane <fiddlo...@gmail.com> wrote:
> > Pandoc already has so many command-line options; I'd rather not > introduce new ones unless it's necessary. Given the ease of translating > from one section format to the other, I don't see that a new option is > warranted. That's why I posed the question as an either-or.
Fair enough.
On Saturday, January 7, 2012 6:06:10 AM UTC+7, Bruce wrote: > I believe at one time, DB 5 had dropped support for numbered sections, in > fact.
I've researched a bit more thoroughly on this topic, but didn't find any indication of sectN being in any way legacy, much less anything about DB ever dropping it - the link you cited was Norm speculating on a hypothetical "start from scratch" standard to replace DB as a whole, not to do with DB itself.
In fact many authors state that although <section> is more convenient for DB newbies, <sectN> is more powerful, allowing different levels to have separate structures, providing better search/retrieval capabilities for DB-native tools, and much better orientation ("situational awareness") while authoring directly in XML - most agreed that better native-DB editors would reduce the need for explicit section levels, but that many still find them necessary given the lack thereof.
--------------------
I still dread the day I have to figure out xslt scripting 8-) and thus would like to make my final (I promise) points on this
Most importantly:
- There is no difference in formatting output or loss of semantic resolution/fidelity going from section-->sectN, but there is going the other way
- The slight disadvantage of using sectN (author inconvenience when working directly in source XML) is completely taken away by using Pandoc.
- Many large publishers standardize on DocBook, but O'Reilly is the most influential regarding the standard itself, having sponsored its creation before setting up the standards bodies.
- It is IMO poor practice to have such a deeply nested structure, and many tools apparently choke when they get too deep - I imagine that is the real reason for ORA's requirement, structural styleguide enforcement 8-)
- Converting from this: <sect1> <sect2> <sect3> <sect4> <sect5>
to only <section> would be a simple search-and-replace, whereas going the other way requires xslt scripting, presumably more complex than Miek's example to handle the case where the author (IM unreasonably) created <section>s nesting more than five deep.
--------------------
I did come across one issue against such a change - it apparently isn't compliant for <section> to be nested within any level of <sectN>, so John's proposed behavior above won't work.
Therefore the only option I can see that wouldn't require a command-line option would be for Pandoc to count the depth and use <sectN> if it's 5 or less deep (could be 6 if the bottom-most were simplesect<http://www.docbook.org/tdg5/en/html/simplesect.html>, but these don't show up in the ToC), and otherwise use <section>s.
I suspect a --sectN flag would be easier, but of course doing nothing is easiest 8-)
Note: I didn't understand xslt two months ago and started using it to create Pandoc2rfc[1]. It took me one afternoon to get the basics. It is easier then I ever imagined.
On Jan 7, 1:53 am, HansBKK <hans...@gmail.com> wrote:
> On Saturday, January 7, 2012 6:06:10 AM UTC+7, Bruce wrote:
> > I believe at one time, DB 5 had dropped support for numbered sections, in
> > fact.
> I've researched a bit more thoroughly on this topic, but didn't find any
> indication of sectN being in any way legacy, much less anything about DB
> ever dropping it - the link you cited was Norm speculating on a
> hypothetical "start from scratch" standard to replace DB as a whole, not to
> do with DB itself.
...
I base this on two things: Norm very clearly stating in 2003 that
numbered sections were a consequence of technical limitations, and a
later post where he notes adding them back to the DB5 schema based on
"popular request." E.g. at one point he did remove them.
And the nested section element certainly is much newer.
Hence my statement.
I think numbered sections are a bit of a hack myself that aren't very
authoring friendly (yes, I've written a book using DocBook, and I
prefer being able to move around structure without changing the actual
nodes).
But admittedly this is a YMMV situation, and there are some mild
processing advantages to numbered sections.
BTW can you explain about pandoc2rfc? I'm curious about your use of AsciiDoc together with Pandoc, your readme says the chain is:
adoc --> dbXML --> rfc
is that right?
I wasn't aware that Pandoc can take DocBookXML as an input, thought that was an output format only?
I would love to see something go from DocBookXML back to AsciiDoc, a couple of people apparently tried over the years but didn't ever get it quite done. . .
And I think I've mentioned that either AsciiDoc or DocBookXML to reST/Sphinx would be so cool, but now we're getting waay OT. 8-)
[ Quoting <hans...@gmail.com> at 07:33 on Jan 7 in "Re: Use of <sect1> i..." ]
> Those would be numbered sec6,sec7... Unless you test for that too. These > switches to <section> for anything above sec5;
> Unfortunately, unless I'm reading the spec wrong, a <section> can't have a > <sectN> for a parent.
> And sect6+ isn't allowed at all, so I'm afraid the user should just somehow be > notified to correct the problem manually and then try again. 8-(
> You get one more level by using simplesect at the bottom, just note these don't > show in the ToC (even 5 is too deep IMO anyway).
That's way I'm against <sectN> output from pandoc, <section> doesn't have these limitions. When writing technical documents deep sections are sometimes needed.
> BTW can you explain about pandoc2rfc? I'm curious about your use of AsciiDoc > together with Pandoc, your readme says the chain is:
> adoc --> dbXML --> rfc
> is that right?
> I wasn't aware that Pandoc can take DocBookXML as an input, thought that was an > output format only?
No, the chain is:
[adoc | pandoc ] -> dbXML -> xslt -> rfc
I just modified my xslt stylesheet so that I can also handle the DocBook as outputted by AsciiDoc. Then this is translated to XML the xml2rfc can understand. And then xml2rfc transforms it to ascii text.
> I would love to see something go from DocBookXML back to AsciiDoc, a couple of > people apparently tried over the years but didn't ever get it quite done. . .
Hmmm, xslt is written for just such a task...
> And I think I've mentioned that either AsciiDoc or DocBookXML to reST/Sphinx > would be so cool, but now we're getting waay OT. 8-)
> [ Quoting <hans...@gmail.com> at 07:33 on Jan 7 in "Re: Use of <sect1> i..." ]
> > Those would be numbered sec6,sec7... Unless you test for that too. These
> > switches to <section> for anything above sec5;
> > Unfortunately, unless I'm reading the spec wrong, a <section> can't have a
> > <sectN> for a parent.
> > And sect6+ isn't allowed at all, so I'm afraid the user should just somehow be
> > notified to correct the problem manually and then try again. 8-(
> > You get one more level by using simplesect at the bottom, just note these don't
> > show in the ToC (even 5 is too deep IMO anyway).
> That's way I'm against <sectN> output from pandoc, <section> doesn't have
> these limitions. When writing technical documents deep sections are sometimes
> needed.
> > BTW can you explain about pandoc2rfc? I'm curious about your use of AsciiDoc
> > together with Pandoc, your readme says the chain is:
> > adoc --> dbXML --> rfc
> > is that right?
> > I wasn't aware that Pandoc can take DocBookXML as an input, thought that was an
> > output format only?
> No, the chain is:
> [adoc | pandoc ] -> dbXML -> xslt -> rfc
> I just modified my xslt stylesheet so that I can also handle the DocBook as
> outputted by AsciiDoc. Then this is translated to XML the xml2rfc can
> understand. And then xml2rfc transforms it to ascii text.
> > I would love to see something go from DocBookXML back to AsciiDoc, a couple of
> > people apparently tried over the years but didn't ever get it quite done. . .
> Hmmm, xslt is written for just such a task...
> > And I think I've mentioned that either AsciiDoc or DocBookXML to reST/Sphinx
> > would be so cool, but now we're getting waay OT. 8-)
