Thread: [Docutils-users] Referencing other ReST pages

Hi,

Over all, I really like ReST a lot.  However, I was wondering what the proper 
method is to reference other ReST pages.

In my case, my desired output /is/ HTML, and I could directly specify links to 
the final deployment site. However, this kind of hardcoding is obviously 
backwards, because it don't allow me to easily change my target deployment 
site.  Also, this solution is HTML-specific.

I was hoping that titles from other pages would be implicit links that other 
pages could refer to, but that doesn't seem to be the case.  I might be 
mincing my ReST jargon, so let me be more clear, just in case.

In file one.txt I have:

    First Title
    ===========

In file two.txt I have:

    (see `First Title`_)

But that doesn't seem to work when I do a rst-buildhtml in the directory 
containing the two files.

By the way, I'm not subscribed to the mailing list, so please reply to the 
E-mail I've provided.  However, I'll also check GMane periodically to see if 
there are any replies.

Thanks for your help,
Sukant

On 8/9/07, Sukant Hajra <g3w...@sn...> wrote:
> Over all, I really like ReST a lot.  However, I was wondering what
> the proper method is to reference other ReST pages.
>
> In my case, my desired output /is/ HTML, and I could directly
> specify links to the final deployment site.

That's how it's done.  Titles are normalized (for details see
http://docutils.sf.net/docs/ref/rst/restructuredtext.html#reference-names),
lowercased, and non-alphanumeric are converted to hypens.  So a
section titled "First Title" will be accessible via "#first-title".

> However, this kind of hardcoding is obviously backwards, because it
> don't allow me to easily change my target deployment site.  Also,
> this solution is HTML-specific.

This is a known open issue, unresolved.

> I was hoping that titles from other pages would be implicit links
> that other pages could refer to, but that doesn't seem to be the
> case.

Correct.  You have to explicitly provide the document reference, which
will not change.  However, other aspects will probably improve.

> By the way, I'm not subscribed to the mailing list, so please reply
> to the E-mail I've provided.

Don't make replying harder for the people you're asking for help.
And that's a very spammy address.

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

Sukant: as noted, there's no way to avoid the explicit document reference 
in standard ReST. However if you keep your ReST documents in Zwiki 
(http://zwiki.org), they can refer to each other by writing the page name 
(which is separate from the ReST headings) in brackets, or as a WikiName.

PS, it might be a nice enhancement to make Zwiki take the page name from 
the first heading in the case of ReST pages. I've opened 
http://zwiki.org/1372 in case there is interest.