Re: forcing heading levels

On 10 January 2014 14:52, Matthew Woehlke <[email protected]> wrote:
> On 2014-01-10 15:32, David Goodger wrote:
>
>> On 10 January 2014 14:19, Matthew Woehlke wrote:
>>>
>>> On 2014-01-10 15:03, David Goodger wrote:
>>>>
>>>> On 10 January 2014 13:46, Matthew Woehlke wrote:
>>>>>
>>>>>
>>>>> I have a really simple document like:
>>>>>
>>>>> Title
>>>>> =====
>>>>>
>>>>> Section
>>>>> -------
>>>>>
>>>>> ...text here...
>>>>>
>>>>> Section
>>>>> -------
>>>>>
>>>>> ...text here...
>>>>>
>>>>>
>>>>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>>>>> "Section"s.
>>>>>
>>>>> Is there any way to force reST to start headings at <h2>, or (less
>>>>> preferable) to skip automatic title detection?
>>>>>
>>>>> Note: This needs to be rendered by a system I don't control, so I can't
>>>>> just throw CSS at the problem.
>>>>
>>>>
>>>> Please see the FAQ:
>>>>
>>>>
>>>> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
>>>
>>>
>>> Sorry, but that is unhelpful. Again, I *don't control* the process used
>>> to
>>> generate HTML.
>>
>>
>> Re that "again": In your original email, I understood "render" in its
>> usual sense, i.e. "render HTML in the browser", and that's a common
>> enough issue to have a section in the FAQ. I was trying to be helpful.
>> Specificity earlier would have avoided the misunderstanding.
>
>
> Fair enough. Apologies for the confusion.
>
>
>>> Therefore, unless there is a way to specify configuration in
>>> the .rst itself (if there is, it's not documented obviously enough), I
>>> can't
>>> use either of the solutions in the FAQ (both of which I already knew
>>> about).
>>>
>>> I need a solution that can be implemented with *only* changes to the .rst
>>> input file.
>>
>>
>> That's not possible, sorry.
>>
>> Do you have control over the .docutils configuration file? If so, you
>> can specify the setting there.
>
>
> I'm not sure. I can place one in the same directory as my .rst, but I have
> no idea if it will be used.
>
>
>> What is the environment in which the HTML is being generated?
>
>
> It's a server that generates dynamic content by fetching an .rst file from a
> git repository and producing HTML on demand. (Vaguely similar idea to
> github's automatic rendering of .rst, but it's not github.)
>
> I probably *could* go monkey with the server if I really had to (it's an
> internal thing developed and run by a coworker), but a general patch risks
> breaking things for other people, and a location-specific hack is getting
> rather egregious.
>
> Modifying it to try to fetch a configuration file might be okay though.

That sounds like the simplest solution. You'll want a file called
"docutils.conf" in the same directory as your reST file.
For details, see
http://docutils.sourceforge.net/docs/user/config.html#configuration-files

>>> So far the best I have come up with is to add:
>>>
>>>   .. disable title promotion
>>>
>>> ...to the very beginning of the document (note the leading indent; the
>>> text
>>> after the comment is of course arbitrary). The rendering is tolerable but
>>> makes it impossible to have the first heading be a title, and adds a
>>> useless
>>> <blockquote> element to the resulting HTML.
>>
>>
>> You can use the "title" directive to specify a document title.
>
>
> Right. Alas, it has no effect (something about how the server generates the
> HTML ignores what reST would otherwise specify the title to be; it doesn't
> work with "real" titles either). It would be nice (but not critical) to have
> an <h1 class="title"> though instead of a plain <h1>.
>
> Thanks for the tip anyway.
>
>
>>> Given that this is apparently a common problem, it seems to me that there
>>> should be a way to handle this more gracefully in the reST syntax
>>> itself...
>>
>>
>> Your specific problem is not common at all. This is the first I've heard
>> of it.
>
>
> Really? There is a FAQ about how it...
>
> I may have a unique wrinkle,

It's the unique wrinkle that I've never seen before.

> but it seems to me it would be useful if there
> was a syntatic way to solve the FAQ.

Yes, it would, and that has come up before. But there are security
concerns, and ultimately it depends on somebody having enough round
tuits for implementation, which hasn't happened yet. See
http://docutils.sourceforge.net/docs/dev/todo.html#misc-settings

-- 
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
CenturyLink Cloud: The Leader in Enterprise Cloud Services.
Learn Why More Businesses Are Choosing CenturyLink Cloud For
Critical Workloads, Development Environments & Everything In Between.
Get a Quote or Start a Free Trial Today. 
http://pubads.g.doubleclick.net/gampad/clk?id=119420431&iu=/4140/ostg.clktrk