From: Mark M. <mar...@mc...> - 2002-10-09 21:04:36
|
Hi, I have this text: <text> Heading 1 ========= All my life, I wanted to be H1. Heading 1.1 ----------- But along came H1, and so now I must be H2. Heading 1.1.1 ************* Yeah, imagine me, I'm stuck at H3! </text> (excluding the <text> start and end tags.) When I run it through tools/html.py, I get unexpected results (below). I was expecting H1, H2, then H3; instead, I get H1, H1, H2. Thanks, // mark <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.2.5: http://docutils.sourceforge.net/" /> <title>Heading 1</title> <link rel="stylesheet" href="default.css" type="text/css" /> </head> <body> <div class="document" id="heading-1"> <h1 class="title">Heading 1</h1> <p>All my life, I wanted to be H1.</p> <div class="section" id="heading-1-1"> <h1><a name="heading-1-1">Heading 1.1</a></h1> <p>But along came H1, and so now I must be H2.</p> <div class="section" id="heading-1-1-1"> <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2> <p>Yeah, imagine me, I'm stuck at H3!</p> </div> </div> </div> </body> </html> - |
From: David G. <go...@us...> - 2002-10-10 00:29:23
|
Mark McEahern wrote: > When I run it through tools/html.py, I get unexpected results (below). I > was expecting H1, H2, then H3; instead, I get H1, H1, H2. Check the "class" attribute on the "h1" tags, and you will see a difference. The first title becomes the document title. From the markup specification: Specifically, there is no way to specify a document title and subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. See the `DocTitle transform`_ for details. (http://docutils.sf.net/spec/rst/reStructuredText.html#document) HTML is being used for dumb formatting; it isn't meant for anything but final display. A stylesheet *is* required, and you're welcome to roll your own. HTML is limited with only H1..H6, so we need to use them sparingly. The HTML Writer uses H1 for document title and H2 for document subtitle, and starts over at H1 for section titles. This will definitely go into the FAQ, being the most frequently asked question so far. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: Greg W. <gw...@me...> - 2002-10-10 13:19:12
|
On 09 October 2002, David Goodger said: > Mark McEahern wrote: > > When I run it through tools/html.py, I get unexpected results (below). I > > was expecting H1, H2, then H3; instead, I get H1, H1, H2. > > Check the "class" attribute on the "h1" tags, and you will see a difference. > > The first title becomes the document title. From the markup specification: For the record, I thought the duelling <h1>s was kind of bogus at first too. But then I put default.css in place, and it all made sense. In fact, I think I like the Docutils way so much -- duplicate the title as a centred <h1>, with regular <h1>s below it -- that I might just start using it myself. Greg -- Greg Ward - software developer gw...@me... MEMS Exchange http://www.mems-exchange.org |
From: Mark M. <mar...@mc...> - 2002-10-10 15:29:22
|
[David Goodger [mailto:go...@us...]] > Check the "class" attribute on the "h1" tags, and you will see a > difference. It took a while for this to sink in. I mean, I saw the class="title". I know how to use CSS. But I just didn't get it. The aha moment came when I saw Greg Ward's reply. I think I just needed to know someone else had struggled with this too. And then I got over it, just like that. If I were to try to express the wherefore of it myself, I'd say, "The first section is special--there's only one of those. Rather than use a plain H1 for that, we use <H1 class="title"/> so that we can use H1 again within the document. The reason we do this? HTML only has H1-H6, so by making H1 do double duty, we effectively reserve these tags to provide 6 levels of heading beyond the single document title." Cheers, // mark - |
From: David G. <go...@us...> - 2002-10-11 01:48:25
|
Mark McEahern wrote: > If I were to try to express the wherefore of it myself, I'd say, ... Thanks, Mark, well put. This was enough to put the FAQ I've slowly been working on over the top. See it in all its glory here: http://docutils.sf.net/FAQ.html I invite questions and suggestions for more FAQ entries. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |