From: Patrick K. O'B. <po...@or...> - 2003-01-21 00:14:49
|
I noticed that including a subtitle changes how the TOC is determined using the html writer. For example, run this content through html.py (the <quote> tags are for this email only and don't appear in the text file): <quote> ================= Structured Text ================= Using Python As An Authoring Tool --------------------------------- :Author: Patrick K. O'Brien :Contact: po...@or... :Date: $Date$ :Web site: http://www.orbtech.com/web/pobrien/ .. contents:: Introduction ============ Imagine, if you will, the following situation. You are a writer. You are a technical writer, actually, who writes books, articles and tutorials about your favorite programming language. To satisfy the needs of your publishers, you must deliver your writing in a variety of formats, such as plaintext, HTML, and XML. And while most other writers use a tool like Microsoft Word, that's just not your style. </quote> Then run the following content: <quote> ================= Structured Text ================= Using Python As An Authoring Tool :Author: Patrick K. O'Brien :Contact: po...@or... :Date: $Date$ :Web site: http://www.orbtech.com/web/pobrien/ .. contents:: Introduction ============ Imagine, if you will, the following situation. You are a writer. You are a technical writer, actually, who writes books, articles and tutorials about your favorite programming language. To satisfy the needs of your publishers, you must deliver your writing in a variety of formats, such as plaintext, HTML, and XML. And while most other writers use a tool like Microsoft Word, that's just not your style. </quote> When "Using Python As An Authoring Tool" is tagged as a subtitle it appears in the TOC. That seems like a mistake to me. Just thought I'd mention it. -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: David G. <go...@py...> - 2003-01-21 00:32:20
|
Patrick K. O'Brien wrote: > I noticed that including a subtitle changes how the TOC is determined using > the html writer. ... > When "Using Python As An Authoring Tool" is tagged as a subtitle it appears > in the TOC. That seems like a mistake to me. Just thought I'd mention it. I don't get those results. In both cases, I get the exact same table of contents, as follows (pseudo-XML):: <topic class="contents" id="contents" name="contents"> <title> Contents <bullet_list> <list_item> <paragraph> <reference id="id1" refid="introduction"> Introduction This was actually taken from the first test data, *with* a subtitle. I checked html.py also -- no anomalies. Please supply the usual: Python, Docutils, & OS versions, and the exact command-line you used. Check for multiple installed versions. Do you have any modified code? Try a clean install of the latest CVS snapshot. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 03:08:30
|
On Monday 20 January 2003 06:34 pm, David Goodger wrote: > Patrick K. O'Brien wrote: > > I noticed that including a subtitle changes how the TOC is determined > > using the html writer. > > ... > > > When "Using Python As An Authoring Tool" is tagged as a subtitle it > > appears in the TOC. That seems like a mistake to me. Just thought I'd > > mention it. > > I don't get those results. In both cases, I get the exact same table of > contents, as follows (pseudo-XML):: > > <topic class="contents" id="contents" name="contents"> > <title> > Contents > <bullet_list> > <list_item> > <paragraph> > <reference id="id1" refid="introduction"> > Introduction > > This was actually taken from the first test data, *with* a subtitle. I > checked html.py also -- no anomalies. It turned out that the sample did work fine, so I sent David the full file. Just for the record, here is what happens with the full file: <topic class="contents" id="contents" name="contents"> <title> Contents <bullet_list> <list_item> <paragraph> <reference id="id1" refid="using-python-as-an-authoring-tool"> Using Python As An Authoring Tool <bullet_list> <list_item> <paragraph> <reference id="id2" refid="introduction"> Introduction -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: David G. <go...@py...> - 2003-01-21 14:51:53
|
Patrick K. O'Brien wrote: >>> I noticed that including a subtitle changes how the TOC is determined >>> using the html writer. ... > It turned out that the sample did work fine, so I sent David the full file. I tried the full file just now, and I see the problem. It's very simple. The table of contents gives a clue (note the nesting): * Using Python As An Authoring Tool * Introduction * reStructuredText * Creating a custom writer for dW tutorials Here's the document subtitle:: Using Python As An Authoring Tool --------------------------------- And here's the last section title:: Creating a custom writer for dW tutorials ----------------------------------------- They both use the same title adornment style -- dash underlines. Therefore the parser places them at the same section level, as evidenced by the TOC above. The solution is to use a different -- and unique -- adornment style for the document subtitle. You could add a dash overline:: ----------------------------------- Using Python As An Authoring Tool ----------------------------------- One nit: it's spelled "Docutils", not "DocUtils" (no StudlyCaps). BTW, the first two sections, "Introduction" and "reStructuredText", are an excellent introduction to the markup. It's good to see a fresh approach -- I'm too close to the project to write objectively. I take it that this is the article you mentioned last month. Is it intended for publication somewhere? Either way, can we use it in the Docutils project once you're done? It would make a great "techie summary" if not an "executive summary". -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 15:16:25
|
On Tuesday 21 January 2003 08:53 am, David Goodger wrote: > I tried the full file just now, and I see the problem. It's very simple. > The table of contents gives a clue (note the nesting): > > * Using Python As An Authoring Tool > > * Introduction > * reStructuredText > > * Creating a custom writer for dW tutorials > > Here's the document subtitle:: > > Using Python As An Authoring Tool > --------------------------------- > > And here's the last section title:: > > Creating a custom writer for dW tutorials > ----------------------------------------- > > They both use the same title adornment style -- dash underlines. > Therefore the parser places them at the same section level, as evidenced > by the TOC above. The solution is to use a different -- and unique -- > adornment style for the document subtitle. You could add a dash > overline:: > > ----------------------------------- > Using Python As An Authoring Tool > ----------------------------------- Okay, I understand now. Two things might help others in the future. First, this entry in FAQ.txt could be a bit more explicit about this requirement: <quote> How can I indicate the document title? Subtitle? ------------------------------------------------- If there's only one highest-level section title at the beginning of a document, it is treated specially, as the document title. Similarly, a lone second-highest-level section title may become the document subtitle if it immediately follows the document title. For example:: This is the Document Title ========================== This is the Document Subtitle ----------------------------- Here's an ordinary paragraph. Counterexample:: Here's an ordinary paragraph. This is *not* a Document Title ============================== The "ordinary paragraph" above the section title prevents it from becoming the document title. </quote> Second, even having read all the docs several times (but not all the specs) I wasn't aware that adding an overline changed how the section title was interpreted. If anything, I had the impression it was a completely optional adornment with no semantic significance. Is that not correct? If not, I suggest making that clear in this section of quickstart.txt, especially the last sentence: <quote> To break longer text up into sections, you use **section headers**. These are a single line of text (one or more words) with an underline (and optionally an overline) in dashes "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable with. The underline/overline must be at least as long as the title text. Be consistent though, since all sections marked with the same underline style are deemed to be at the same level:: </quote> -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: David G. <go...@py...> - 2003-01-21 18:57:51
|
Patrick K. O'Brien wrote: > Okay, I understand now. Two things might help others in the future. First, > this entry in FAQ.txt could be a bit more explicit about this requirement: Done: <http://docutils.sf.net/FAQ.html>, section 2.5. > Second, even having read all the docs several times (but not all the specs) > I wasn't aware that adding an overline changed how the section title was > interpreted. If anything, I had the impression it was a completely optional > adornment with no semantic significance. Is that not correct? If not, I > suggest making that clear in this section of quickstart.txt, especially the > last sentence: Done: <http://docutils.sf.net/docs/rst/quickstart.html#sections>. I have also modified the markup spec: <http://docutils.sf.net/spec/rst/reStructuredText#sections>. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 19:28:58
|
On Tuesday 21 January 2003 12:59 pm, David Goodger wrote: > > Done: <http://docutils.sf.net/FAQ.html>, section 2.5. > > Done: <http://docutils.sf.net/docs/rst/quickstart.html#sections>. That's much better. > I have also modified the markup spec: > <http://docutils.sf.net/spec/rst/reStructuredText#sections>. Typo in url fixed below: <http://docutils.sf.net/spec/rst/reStructuredText.html#sections> -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 15:18:13
|
On Tuesday 21 January 2003 08:53 am, David Goodger wrote: > One nit: it's spelled "Docutils", not "DocUtils" (no StudlyCaps). Doh! I'm usually pretty good about these things, and I was fully aware that the proper spelling was mentioned in the FAQ, and, yet, I still messed it up. Ugh! :-( -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 15:27:10
|
On Tuesday 21 January 2003 08:53 am, David Goodger wrote: > BTW, the first two sections, "Introduction" and "reStructuredText", are > an excellent introduction to the markup. It's good to see a fresh > approach -- I'm too close to the project to write objectively. Thanks, glad you liked it. > I take it > that this is the article you mentioned last month. Is it intended for > publication somewhere? Either way, can we use it in the Docutils project > once you're done? It would make a great "techie summary" if not an > "executive summary". Right now it is just something I'm playing with as I figure out how to use ReST. If it turns into something decent I will try to get it published. At this point I've actually got more demand for articles than time to write them. I'm hoping ReST and Emacs increase my productivity. (I just switched to Emacs from Vim and the transition is a bit painful, even though I never got very comfortable with Vim either. I swear this is the last time I change text editors!) I'll definitely figure out a way to make the content available for you to include in the Docutils project. -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: Aahz <aa...@py...> - 2003-01-21 17:18:54
|
On Tue, Jan 21, 2003, Patrick K. O'Brien wrote: > > Right now it is just something I'm playing with as I figure out how to use > ReST. If it turns into something decent I will try to get it published. At > this point I've actually got more demand for articles than time to write > them. I'm hoping ReST and Emacs increase my productivity. (I just switched > to Emacs from Vim and the transition is a bit painful, even though I never > got very comfortable with Vim either. I swear this is the last time I > change text editors!) Why did you switch to emacs? (I loathe emacs, and can't imagine anyone familiar with vi switching.) -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "I used to have a .sig but I found it impossible to please everyone..." --SFJ |
From: Patrick K. O'B. <po...@or...> - 2003-01-21 17:49:42
|
On Tuesday 21 January 2003 11:18 am, Aahz wrote: > Why did you switch to emacs? (I loathe emacs, and can't imagine anyone > familiar with vi switching.) Resistance was futile. ;-) With all the writing I'm doing--both code and text--I decided to give in and live in an editor that did everything. Simple as that. I gave Vim a try and it just never clicked for me. Emacs doesn't exactly click either, but I've run out of options. -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." ----------------------------------------------- |
From: Michael H. <mw...@py...> - 2003-01-21 18:02:45
|
Aahz <aa...@py...> writes: > Why did you switch to emacs? Becuase he saw the light :) /\ || ,--------'`---------. | NOTE THIS, PLEASE | `-------------------' Is anyone working on a rest emacs mode? text-mode is pretty close, but things to keep titles in sync and help with tables would be nice, not to mention jumping between links and references... Cheers, M. -- FORD: Just pust the fish in your ear, come on, it's only a little one. ARTHUR: Uuuuuuuuggh! -- The Hitch-Hikers Guide to the Galaxy, Episode 1 |
From: Beni C. <cb...@te...> - 2003-01-22 09:53:41
|
On 2003-01-21, Michael Hudson wrote: > Is anyone working on a rest emacs mode? text-mode is pretty close, but > things to keep titles in sync and help with tables would be nice, not to > mention jumping between links and references... > One of these is already solved: for "full" tables, there is an excellent ``table.el`` floating somewhere that can edit contents of a cell by creating a temporay buffer), resize cells, etc. Actually the the spec for full tables refers to it as a justification of the syntax... -- Beni Cherniavsky <cb...@tx...> |