Re: forcing heading levels

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.

>> 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, but it seems to me it would be useful if 
there was a syntatic way to solve the FAQ.

-- 
Matthew

------------------------------------------------------------------------------
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