[Docutils-users] Second level before the first level headline?

[Matěj Cepl]

Hi,

I am trying to reformat the book “The Everlasting Man” by Gilbert Keith
Chesterton. I found a public domain text on
http://gutenberg.net.au/ebooks01/0100311.txt and I would like to
reformat it into rST and regenerate as ePub with pandoc (or perhaps even
https://pypi.python.org/pypi/epubmaker/). The rST file I have created is
http://mcepl.fedorapeople.org/tmp/everlasting-man.rst

The problem is that the ePub I have created
(http://mcepl.fedorapeople.org/tmp/everlasting-man.epub) has completely
wrong structure. I cannot change the fact that Chesterton (or the
publisher, more likely) decided that the Introduction (level 2 heading)
precedes The Part I. (level 1 heading). See the attached screenshot of
the outline how it is wrong.

Is there way how to persuade pandoc (or other rST tools) that what I
want to be the level 2 heading (marked by single dashes underlining) is
really that, and that level 1 heading is marked by by both underlining
and overlining?

Thank you,

Matěj
--
http://www.ceplovi.cz/matej/, Jabber: ***@ceplovi.cz
GPG Finger: 89EF 4BC6 288A BF43 1BAB 25C3 E09F EF25 D964 84AC

..every Man has a Property in his own Person. This no Body has
any Right to but himself. The Labour of his Body, and the Work of
his Hands, we may say, are properly his. .... The great and chief
end therefore, of Mens uniting into Commonwealths, and putting
themselves under Government, is the Preservation of their
Property.
-- John Locke, "A Treatise Concerning Civil Government"

[Matěj Cepl]

you say you are reformatting
why not underline your level1 with =
make the file more reST complient so one is able to switch tools and
must not modify tools

I don't understand ... my point was that (AFAIK) docutils doesn't have a
fixed marking for the different levels of headlines, but it assumes that
the first headline it finds is on the first level. Am I wrong?

Matěj

[engelbert gruber]

Post by Matěj Cepl

you say you are reformatting
why not underline your level1 with =
make the file more reST complient so one is able to switch tools and
must not modify tools

I don't understand ... my point was that (AFAIK) docutils doesn't have a
fixed marking for the different levels of headlines, but it assumes that
the first headline it finds is on the first level. Am I wrong?

now i understand better.
you are correct

means "preparatory note" and "introduction ..." are no section headings
numbering would result in 0.1 ... sorry i do not see an easy way out now

have a look at gutenberg AFAIR they have a titlepage before the book title,
wrapping books in gutenberg pages.

all the best e

[Peter Funk]

Matěj Cepl wrote 17.05.2014 at 13:35:
...

Post by Matěj Cepl
Is there way how to persuade pandoc (or other rST tools) that what I
want to be the level 2 heading (marked by single dashes underlining) is
really that, and that level 1 heading is marked by by both underlining
and overlining?

Hmmm.... The internal model of docutils uses a tree to represent the
hierarchical structure. So I assume David thought that orphaned
level-2 sections without a level-1 parent are normally not needed
at all. I would simply put an artificial Part 0 header into the
text to solve this issue. For example this one should work::

----------------------------------------
PART 0. — PEPATORY NOTE AND INTRODUCTION
----------------------------------------

Regards, Peter Funk

[Roger Gammans]

Post by Peter Funk
...

Post by Matěj Cepl
Is there way how to persuade pandoc (or other rST tools) that what I
want to be the level 2 heading (marked by single dashes underlining) is
really that, and that level 1 heading is marked by by both underlining
and overlining?

Hmmm.... The internal model of docutils uses a tree to represent the
hierarchical structure. So I assume David thought that orphaned
level-2 sections without a level-1 parent are normally not needed
at all. I would simply put an artificial Part 0 header into the

And IIRC, internally I don't think a section needs a title. It only
needs one to introduce it to the parser. There are a number of
transforms available which manipulate the titles independently the
sections. [See --section-subtitles , --no-doc-title].

I don't think there is a transform in the default tooling that does what
the OP needs but you could write your own if you are happy to have
custom python in you tool-chain.

[David Goodger]

Post by Peter Funk
...

Post by Matěj Cepl
Is there way how to persuade pandoc (or other rST tools) that what I
want to be the level 2 heading (marked by single dashes underlining) is
really that, and that level 1 heading is marked by by both underlining
and overlining?

No. A document has to provide a consistent set of headers that follow
the structure of that document. The problem with the document in
question is that it's missing a level. You'll have to work around it
(examples below).

Post by Peter Funk
Hmmm.... The internal model of docutils uses a tree to represent the
hierarchical structure. So I assume David thought that orphaned
level-2 sections without a level-1 parent are normally not needed
at all.

It's not that they're not needed (such cases are often seen, as in
books like this), it's that such a structure makes no sense. Documents
normally have hierarchical structure, but books are designed by
people, and people are not regular like data structures. So we end up
with a nonsensical tree-like structure where one of the nodes is
missing. How to deal with it? Either remove the inconsistency, or fake
the missing node.

Post by Peter Funk
I would simply put an artificial Part 0 header into the
----------------------------------------
PART 0. — PEPATORY NOTE AND INTRODUCTION
----------------------------------------

I agree. That header could then be styled and processed specially.

A quick and dirty hack would be to have an empty title for the Part 0
header, like this:

-----
\
-----
.. The above is a level-1 header to give this document a reasonable structure.

That may be enough to produce a reasonable ePub document.

Another solution (cleaner, IMO) would be to make the preparatory note
and introduction sections the same level as the "parts" (or
vice-versa). In other words, remove the inconsistency. You could
assign a class to those sections and style or process them specially,
if desired.

[Matěj Cepl]

Post by David Goodger
A quick and dirty hack would be to have an empty title for the Part 0
-----
\
-----
.. The above is a level-1 header to give this document a reasonable structure.

Works lovely … http://mcepl.fedorapeople.org/tmp/everlasting-man.epub

Thanks,

Matěj

[Matěj Cepl]

Post by David Goodger

Post by Peter Funk
I would simply put an artificial Part 0 header into the
----------------------------------------
PART 0. — PEPATORY NOTE AND INTRODUCTION
----------------------------------------

I agree. That header could then be styled and processed specially.

How can I do that? The ideal would be some kind of equivalent of
'display: none' class (just for ePub is possible).

Post by David Goodger
A quick and dirty hack would be to have an empty title for the Part 0
-----
\
-----
.. The above is a level-1 header to give this document a reasonable structure.

Actually this break docutils parser apparently (pandoc is happy, but
rst2html is not). So I use this hack instead:

-------------------------------------
|empty|
-------------------------------------

.. |empty| unicode:: 0x20

Best,

Matěj

[David Goodger]

Post by Matěj Cepl

Post by David Goodger

Post by Peter Funk
I would simply put an artificial Part 0 header into the
----------------------------------------
PART 0. — PEPATORY NOTE AND INTRODUCTION
----------------------------------------

I agree. That header could then be styled and processed specially.

How can I do that? The ideal would be some kind of equivalent of
'display: none' class (just for ePub is possible).

Use the "class" directive before the header to assign a class to a
section. After that, it's a matter of CSS or equivalent.

[Beni Cherniavsky-Paskin]

It makes sense that an Introduction stands alone outside PARTs but
then it's semantically a level-1 section.

If the publisher (or you) decide to have its heading smaller than a
PART, that's a formatting choice, not sematic.
At best its semantics is "a special kind of level-1 section".
How about::

.. class:: front-matter

--------------
Prefatory Note
--------------

text...

.. class:: front-matter

------------
Introduction
------------

text...

-----------
PART I. FOO
-----------

I. BAR
------

And then use CSS to style ``div.section.front-matter h1`` differently.
(Classes work with rst2html, ignored by pandoc)

Actually, looking at the Gutenberg link, I see PREPATORY NOTE,
INTRODUCTION and PARTs all "formatted" in the same way (capitals after
``* * * `` line).
If you're happy with that, maybe you don't need any special classes/styling.

Hi,
I am trying to reformat the book “The Everlasting Man” by Gilbert Keith
Chesterton. I found a public domain text on
http://gutenberg.net.au/ebooks01/0100311.txt and I would like to
reformat it into rST and regenerate as ePub with pandoc (or perhaps even
https://pypi.python.org/pypi/epubmaker/). The rST file I have created is
http://mcepl.fedorapeople.org/tmp/everlasting-man.rst
The problem is that the ePub I have created
(http://mcepl.fedorapeople.org/tmp/everlasting-man.epub) has completely
wrong structure. I cannot change the fact that Chesterton (or the
publisher, more likely) decided that the Introduction (level 2 heading)
precedes The Part I. (level 1 heading). See the attached screenshot of
the outline how it is wrong.
Is there way how to persuade pandoc (or other rST tools) that what I
want to be the level 2 heading (marked by single dashes underlining) is
really that, and that level 1 heading is marked by by both underlining
and overlining?
Thank you,
Matěj
--
GPG Finger: 89EF 4BC6 288A BF43 1BAB 25C3 E09F EF25 D964 84AC
..every Man has a Property in his own Person. This no Body has
any Right to but himself. The Labour of his Body, and the Work of
his Hands, we may say, are properly his. .... The great and chief
end therefore, of Mens uniting into Commonwealths, and putting
themselves under Government, is the Preservation of their
Property.
-- John Locke, "A Treatise Concerning Civil Government"
------------------------------------------------------------------------------
"Accelerate Dev Cycles with Automated Cross-Browser Testing - For FREE
Instantly run your Selenium tests across 300+ browser/OS combos.
Get unparalleled scalability from the best Selenium testing platform available
Simple to use. Nothing to install. Get started now for free."
http://p.sf.net/sfu/SauceLabs
_______________________________________________
Docutils-users mailing list
https://lists.sourceforge.net/lists/listinfo/docutils-users
Please use "Reply All" to reply to the list.

[Guenter Milde]

Post by Beni Cherniavsky-Paskin
It makes sense that an Introduction stands alone outside PARTs but
then it's semantically a level-1 section.
If the publisher (or you) decide to have its heading smaller than a
PART, that's a formatting choice, not sematic.
At best its semantics is "a special kind of level-1 section".
.. class:: front-matter
--------------
Prefatory Note
--------------
text...

...

Alternatively, one could use the "topic" or "rubric" directives. Both
provide titles for text parts that are not part of the document's structure.

Günter