docutils-users

[Docutils-users] Specifying explicit ID tags in HTML output

[David A. <Da...@Ac...>]

In some documents, I'd like the id tags associated with anchors to remain 
constant in the face of section name changes.  In other words, I'd like to mark up

Requirement 123123: This part may change
----------------------------------------

With something, so that I could always refer to http:/.../foo.html#something

and have it point to the <a> tag which docutils currently generates with the 
id "requirement-this-part-may-change" or something like that.

A proposal would be to use markup like:

	#permanent: Changeable title

which would produce:

	<div class="section" id="permanent">
	<h1>
	<a id="permanent" name="changeable-title">permanent: Changeable 	title</a>
	</h1>

Is there already something somewhere that does that?

--david

Re: [Docutils-users] Specifying explicit ID tags in HTML output

[David G. <go...@py...>]

David Ascher wrote:
> Is there already something somewhere that does that?

Indeed there is.  Use an internal hyperlink target::

    .. _permanent name:

    Requirement 123123: This part may change
    ----------------------------------------

    Ordinary text here.

The target text will be converted to an ID by lowcasing and converting
all punctuation and whitespace to dashes.  The above target could be
referred to as:

    http:/.../foo.html#permanent-name

The form of the permanent name can be whatever you like.

-- 
David Goodger  <go...@py...>  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/