Discussion:
[Docutils-users] Section titles, with or without multiple sections in document
Ben Finney
2015-01-07 04:53:05 UTC
Permalink
Howdy all,

How can I disable the special-case treatment of a lone section title as
the document title?

The default reST parser treats a lone section title as a special case,
promoting it as the document title. What I want is to disable that
behaviour, and have the first section treated as a section regardless of
whether any sections follow it.

A document with two top-level sections is parsed as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
<section ids="second-section" names="second\ section">
<title>
Second Section
<paragraph>
Praesent eleifend ligula eget luctus consectetur.
=====

But if the document has only one top-level section, the special case
applies and I don't get the sections as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document ids="first-section" names="first\ section" source="<stdin>" title="First Section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====

What I want is:

=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====

In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?
--
\ “A politician is an animal which can sit on a fence and yet |
`\ keep both ears to the ground.” —Henry L. Mencken |
_o__) |
Ben Finney
Ben Finney
2015-01-07 05:20:45 UTC
Permalink
Post by Ben Finney
But if the document has only one top-level section
Sorry, I gave the wrong example. Here is an example that shows the
Post by Ben Finney
=====
$ cat foo.txt
First Section
=============
Lorem ipsum, dolor sit amet.
$ rst2pseudoxml < foo.txt
<document ids="first-section" names="first\ section" source="<stdin>" title="First Section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====
What I want is:

=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====

In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?
--
\ “… a Microsoft Certified System Engineer is to information |
`\ technology as a McDonalds Certified Food Specialist is to the |
_o__) culinary arts.” —Michael Bacarella |
Ben Finney


------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply t
David Goodger
2015-01-07 15:43:24 UTC
Permalink
Post by Ben Finney
Post by Ben Finney
But if the document has only one top-level section
Sorry, I gave the wrong example. Here is an example that shows the
Post by Ben Finney
=====
$ cat foo.txt
First Section
=============
Lorem ipsum, dolor sit amet.
$ rst2pseudoxml < foo.txt
<document ids="first-section" names="first\ section" source="<stdin>" title="First Section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====
=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====
In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?
http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
--
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.
Ben Finney
2015-01-08 01:52:43 UTC
Permalink
Post by David Goodger
Post by Ben Finney
=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====
In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?
http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
Thanks. Okay, that is a setting on the Publisher (and, according to the
docs, normally set by configuration file or command-line).

For the task at hand (if it matters, I am transforming a changelog
document to structured release data), I want all the settings to be
internally managed.

So far I've only needed to make a custom Writer class and a custom
Translator class. Unit tests for those are already cumbersome; I would
really prefer not to need creating yet another custom class.

In order to modify that setting (‘doctitle_xform’), do I need to make a
custom Publisher class too? Or can I have the Writer somehow override
it?
--
\ “Never express yourself more clearly than you are able to |
`\ think.” —Niels Bohr |
_o__) |
Ben Finney
David Goodger
2015-01-08 02:28:49 UTC
Permalink
Post by Ben Finney
Post by David Goodger
Post by Ben Finney
=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
<section ids="first-section" names="first\ section">
<title>
First Section
<paragraph>
Lorem ipsum, dolor sit amet.
=====
In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?
http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
Thanks. Okay, that is a setting on the Publisher (and, according to the
docs, normally set by configuration file or command-line).
For the task at hand (if it matters, I am transforming a changelog
document to structured release data), I want all the settings to be
internally managed.
So far I've only needed to make a custom Writer class and a custom
Translator class. Unit tests for those are already cumbersome; I would
really prefer not to need creating yet another custom class.
In order to modify that setting (‘doctitle_xform’), do I need to make a
custom Publisher class too? Or can I have the Writer somehow override
it?
Just pass the configuration setting to the standard Publisher or
convenience function:
http://docutils.sourceforge.net/docs/api/publisher.html#configuration
--
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All"
Ben Finney
2015-01-08 02:39:05 UTC
Permalink
Post by David Goodger
Post by Ben Finney
Okay, that is a setting on the Publisher (and, according to the
docs, normally set by configuration file or command-line).
For the task at hand (if it matters, I am transforming a changelog
document to structured release data), I want all the settings to be
internally managed. […]
In order to modify that setting (‘doctitle_xform’), do I need to make a
custom Publisher class too? Or can I have the Writer somehow override
it?
Just pass the configuration setting to the standard Publisher or
http://docutils.sourceforge.net/docs/api/publisher.html#configuration
What I'd like is for any code using this custom Writer, to get that
behaviour by default (i.e. not need to even know about the
‘doctitle_xform’ option). Can the Writer take care of that option in
such a way that the client code doesn't need to know about it?
--
\ “Shepherds … look after their sheep so they can, first, fleece |
`\ them and second, turn them into meat. That's much more like the |
_o__) priesthood as I know it.” —Christopher Hitchens, 2008-10-29 |
Ben Finney
David Goodger
2015-01-08 03:25:46 UTC
Permalink
Post by Ben Finney
Post by David Goodger
Post by Ben Finney
Okay, that is a setting on the Publisher (and, according to the
docs, normally set by configuration file or command-line).
For the task at hand (if it matters, I am transforming a changelog
document to structured release data), I want all the settings to be
internally managed. […]
In order to modify that setting (‘doctitle_xform’), do I need to make a
custom Publisher class too? Or can I have the Writer somehow override
it?
Just pass the configuration setting to the standard Publisher or
http://docutils.sourceforge.net/docs/api/publisher.html#configuration
What I'd like is for any code using this custom Writer, to get that
behaviour by default (i.e. not need to even know about the
‘doctitle_xform’ option). Can the Writer take care of that option in
such a way that the client code doesn't need to know about it?
Yes, it can (just monkey-patch the settings object), but it shouldn't.

Don't you have a front-end app? It should do the configuration.
--
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Ple
Ben Finney
2015-01-08 06:36:48 UTC
Permalink
Post by David Goodger
Post by Ben Finney
What I'd like is for any code using this custom Writer, to get that
behaviour by default (i.e. not need to even know about the
‘doctitle_xform’ option). Can the Writer take care of that option in
such a way that the client code doesn't need to know about it?
Yes, it can (just monkey-patch the settings object), but it shouldn't.
Fair enough. I can understand it makes the API clearer.
Post by David Goodger
Don't you have a front-end app? It should do the configuration.
Well, the extra levels of indirection complicate my unit tests. But not
hugely, and the result is still good.

Thanks for the help.
--
\ “I turned to speak to God/About the world's despair; But to |
`\ make bad matters worse/I found God wasn't there.” —Robert Frost |
_o__) |
Ben Finney


------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Pl
Loading...