Menu
▾
▴
docutils-develop
|
From: Aahz <aa...@py...> - 2002-10-09 01:24:48
|
Let's suppose I've got a figure, and I want to refer to it (e.g. "See figure 3.11"), how do I do that? (I've now read much of reStructuredText.txt, so I've got a better grasp of what's available (i.e. knowing about "::"), but I'm still having some trouble knowing which constructs are best for specific purposes.) I'm probably going to create some kind of ToC directive that goes in an include file so I can create cross-chapter references easily. So whatever syntax you give me ought to allow me to say <chapter name>:<figure name> and have it get processed properly. I'm thinking that interpreted text is likely the way to go, but David has previously expressed some distaste for interpreted text that gets completely removed. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: David G. <go...@us...> - 2002-10-09 02:20:47
|
Aahz wrote:
> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
> figure 3.11"), how do I do that?
I don't know. Currently, figures don't have any attribute which can be
referenced. Perhaps a "name" option on figures? For example::
.. figure:: image.png
:name: image's name
DocBook and others do this kind of reference (all references, actually)
using IDs. reStructuredText uses reference names, not IDs, and the names
are converted to IDs internally. Perhaps Docutils needs an explicit ID
mechanism, something like::
.. figure:: image.png
:id: image-id
How to refer to a figure though? Perhaps something like this::
See :figure:`image's name`.
This could produce "See figure 1.", assuming that figures grow a numbering
mechanism as well (they don't have one yet).
In order to get "figure 3.11"-style references, we'd need sequences, such as
chapter numbers, that are persistent across multi-file processing runs.
This is getting complicated.
> (I've now read much of reStructuredText.txt, so I've got a better grasp
> of what's available (i.e. knowing about "::"), but I'm still having some
> trouble knowing which constructs are best for specific purposes.)
Such as? Have you looked at http://docutils.sf.net/docs/rst/quickref.html?
(OT: It would be nice if this file were converted to "self-hosted"
reStructuredText. It's the only hand-coded HTML in the project.) The
tools/test.txt file (http://docutils.sf.net/tools/test.html) may also
provide clues.
> I'm probably going to create some kind of ToC directive that goes in an
> include file so I can create cross-chapter references easily.
I don't follow. Examples? Perhaps this To-Do entry is relevant:
* Perhaps store a name-to-id mapping file? This could be stored
permanently, read by subsequent processing runs, and updated
with new entries. ("Persistent ID mapping"?)
(To-Do list is here: http://docutils.sf.net/spec/notes.html)
> So whatever syntax you give me ought to allow me to say
> <chapter name>:<figure name> and have it get processed properly.
I believe this is a larger issue, applicable to all kinds of references. It
should be kept separate from figure references. There's already an entry in
the To-Do list, which requires more thought:
* Support generic hyperlink references to targets in other
documents? Not in an HTML-centric way, though (it's trivial to
say ``http://www.example.com/doc#name``, and useless in non-HTML
contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
2001-08-10.
> I'm thinking that interpreted text is likely the way to go, but David
> has previously expressed some distaste for interpreted text that gets
> completely removed.
I wouldn't worry about that. If interpreted text ends up being the way to
go, then so be it (interpreted text isn't actually implemented yet; it
awaits real world use cases). More importantly, we need to work out the
mechanism before we can say what syntax applies.
--
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: Aahz <aa...@py...> - 2002-10-09 03:28:49
|
On Tue, Oct 08, 2002, David Goodger wrote: > Aahz wrote: >> >> Let's suppose I've got a figure, and I want to refer to it (e.g. "See >> figure 3.11"), how do I do that? > > I don't know. Currently, figures don't have any attribute which can be > referenced. Perhaps a "name" option on figures? For example:: > > .. figure:: image.png > :name: image's name > > DocBook and others do this kind of reference (all references, actually) > using IDs. reStructuredText uses reference names, not IDs, and the names > are converted to IDs internally. Perhaps Docutils needs an explicit ID > mechanism, something like:: > > .. figure:: image.png > :id: image-id > > How to refer to a figure though? Perhaps something like this:: > > See :figure:`image's name`. > > This could produce "See figure 1.", assuming that figures grow a numbering > mechanism as well (they don't have one yet). That's roughly what I was thinking of. There will need to be a generic naming and numbering mechanism, because other kinds of document elements (e.g. tables) will want references and numbering. > In order to get "figure 3.11"-style references, we'd need sequences, > such as chapter numbers, that are persistent across multi-file > processing runs. This is getting complicated. That's one way of doing it, but see below. >> (I've now read much of reStructuredText.txt, so I've got a better grasp >> of what's available (i.e. knowing about "::"), but I'm still having some >> trouble knowing which constructs are best for specific purposes.) > > Such as? Have you looked at http://docutils.sf.net/docs/rst/quickref.html? > (OT: It would be nice if this file were converted to "self-hosted" > reStructuredText. It's the only hand-coded HTML in the project.) The > tools/test.txt file (http://docutils.sf.net/tools/test.html) may also > provide clues. Well, such as this figure referencing problem. ;-) Don't worry, I'll mention others as I come across them. >> I'm probably going to create some kind of ToC directive that goes in an >> include file so I can create cross-chapter references easily. > > I don't follow. Examples? Perhaps this To-Do entry is relevant: > > * Perhaps store a name-to-id mapping file? This could be stored > permanently, read by subsequent processing runs, and updated > with new entries. ("Persistent ID mapping"?) Not quite. What I'm thinking more of (at least for starters) is an extremely simple list of references to reST documents. Initially, it'd just be for the purpose of auto-numbering references to those documents (i.e. chapter references); later on, it could evolve into a true multi-file system for garnering internal references. But because I'm focused on book writing at this point, hyperlinks are *not* what I'm after. So for now I'm likely to hard-code the actual figure numbers (but not the chapter numbers) for cross-chapter references. >> I'm thinking that interpreted text is likely the way to go, but David >> has previously expressed some distaste for interpreted text that gets >> completely removed. > > I wouldn't worry about that. If interpreted text ends up being the way to > go, then so be it (interpreted text isn't actually implemented yet; it > awaits real world use cases). More importantly, we need to work out the > mechanism before we can say what syntax applies. To repeat what I've said above differently, one concern I've had in reading through the reST docs is the extent to which references, particularly external references, are often equated with hyperlinks. That's simply not particularly applicable to my domain. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: David G. <go...@us...> - 2002-10-09 04:06:31
|
Aahz wrote: > To repeat what I've said above differently, one concern I've had in > reading through the reST docs is the extent to which references, > particularly external references, are often equated with hyperlinks. > That's simply not particularly applicable to my domain. And to paraphrase what I've said before, that's simply because the only well-developed Writer so far is for HTML. Writers for OpenOffice XML or RTF will present their own challenges. I'm not concerned at all. I'm sure such a Writer will influence the Docutils document tree structure and system internals, and I welcome that influence -- I'm sure it will improve the system. Don't blame the tool for not being able to do a job it wasn't designed to do; instead, let's improve the tool so it *can* do the job, naturally. -- 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: <gr...@us...> - 2002-10-09 09:52:47
|
On Tue, 8 Oct 2002, Aahz wrote: > On Tue, Oct 08, 2002, David Goodger wrote: > > Aahz wrote: <snip> </snip> > (i.e. chapter references); later on, it could evolve into a true > multi-file system for garnering internal references. But because I'm > focused on book writing at this point, hyperlinks are *not* what I'm > after. as a notice to book writers, maybe the latex backend is good enough. i am willing to give support for real problems, meaning not the pathologic test.txt. sorry my time is limited and there are so much possibilities. so if someone wants a pdf from his rest-docs contact me. maybe we schould split test.txt, so one could get a compliance page, which construct works how good with which writer. ad ToC: maybe have a look into latex style: toc = table of contents, lot = list of tables, lof = list of figures and when generating pdf these are bookmarks (i guess). cheers -- BINGO: Ich komme auf Sie zu --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+ |
|
From: Aahz <aa...@py...> - 2002-10-09 12:03:02
|
On Wed, Oct 09, 2002, gr...@us... wrote: > On Tue, 8 Oct 2002, Aahz wrote: >> >> (i.e. chapter references); later on, it could evolve into a true >> multi-file system for garnering internal references. But because I'm >> focused on book writing at this point, hyperlinks are *not* what I'm >> after. > > as a notice to book writers, maybe the latex backend is good enough. > i am willing to give support for real problems, meaning not the pathologic > test.txt. sorry my time is limited and there are so much possibilities. > > so if someone wants a pdf from his rest-docs contact me. You're missing the background here. ;-) Unfortunately, the book I'm writing needs to be delivered in Word format. Based on the information available to me, I've decided that the best approach is to output OpenOffice.org XML format from reST, then use OpenOffice to convert to Word. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: engelbert g. <be...@ch...> - 2002-10-09 17:04:56
|
On Wed, 9 Oct 2002, Aahz wrote: > On Wed, Oct 09, 2002, gr...@us... wrote: > > On Tue, 8 Oct 2002, Aahz wrote: > >> > >> (i.e. chapter references); later on, it could evolve into a true > >> multi-file system for garnering internal references. But because I'm > >> focused on book writing at this point, hyperlinks are *not* what I'm > >> after. > > > > as a notice to book writers, maybe the latex backend is good enough. > > i am willing to give support for real problems, meaning not the pathologic > > test.txt. sorry my time is limited and there are so much possibilities. > > > > so if someone wants a pdf from his rest-docs contact me. > > You're missing the background here. ;-) Unfortunately, the book I'm not really, although this background dates back a month, i can remember someone asking for word output. but i can not remember if it would suffice to convert in one direction only or if the review would be done in word asf .. anyway my offer is to you too, but not exclusive. > writing needs to be delivered in Word format. Based on the information > available to me, I've decided that the best approach is to output > OpenOffice.org XML format from reST, then use OpenOffice to convert to > Word. -- engelbert gruber email: eng...@ss... |
|
From: <gr...@us...> - 2002-10-10 08:15:49
|
http://jakarta.apache.org/poi/index.html claims to being able to write ole-documents (sounds like a bad zip-file) run docutils under jython and use it ? see the BINGO and remember "'e's pinning for the fjords" -- BINGO: Remarkable bird, the Norwegian Blue. --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+ |
|
From: Aahz <aa...@py...> - 2002-10-10 13:33:19
|
On Thu, Oct 10, 2002, gr...@us... wrote: > > http://jakarta.apache.org/poi/index.html > claims to being able to write ole-documents (sounds like a bad zip-file) > run docutils under jython and use it ? No, at this point, I think I'd rather not drag in Java/Jython. It's already taking longer than I'd hoped to learn how to use reST. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: David G. <go...@us...> - 2002-10-11 01:55:56
|
Aahz wrote: > It's already taking longer than I'd hoped to learn how to use reST. That's unfortunate. Any insights into how it might be made easier? Or is it because you're not only learning it as a user, but also as a developer? Thinking about index directives and multi-chapter/file book processing adds complexity. -- 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: Aahz <aa...@py...> - 2002-10-11 03:07:11
|
On Thu, Oct 10, 2002, David Goodger wrote: > Aahz wrote: >> >> It's already taking longer than I'd hoped to learn how to use reST. > > That's unfortunate. Any insights into how it might be made easier? > Or is it because you're not only learning it as a user, but also as a > developer? Thinking about index directives and multi-chapter/file book > processing adds complexity. It's having to learn reST both inside and out that's the problem, yes; I need to figure out not only the reST syntax, but also which bits apply most appropriately to the demands of writing a book, *and* I have to figure out how to convert the bits into usable output. Until reST settles down a bit more and has more than one full-fledged output format, I don't think it *can* be much easier -- annoying as it is. I'm about 70% of the way to a minimal system for converting a reST file into OpenOffice format. Please note the emphasis on "minimal", and it's uuugly. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: David G. <go...@us...> - 2002-10-10 00:50:22
|
Engelbert Gruber wrote:
> i am willing to give support for real problems, meaning not the
> pathologic test.txt.
I've got to call you on this one. "Pathological"?!? That is a gross
misrepresentation. The tools/test.txt file is pretty complete (*not*
100% though), but there's nothing in it that can't be found elsewhere.
Certainly nothing pathological!
> sorry my time is limited and there are so much possibilities.
Join the club. ;-)
> maybe we schould split test.txt, so one could get a compliance page,
> which construct works how good with which writer.
tools/test.txt *is* the compliance file, the only one we've got. I
don't see a need for a weakened compliance test.
As I've said before, to get out of the sandbox the LaTeX Writer
doesn't have to handle every construct perfectly, but it *does* have
to handle every construct without (a) crashing or (b) silently
omitting data. If the Writer can't handle a particular construct,
have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
output a simpler form, such as the string returned by the
``.astext()`` node method. I earlier objected to the presence of many
Writer/Visitor methods containing only "pass", which is not
acceptable.
Errors should never pass silently.
Unless explicitly silenced.
--
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: <gr...@us...> - 2002-10-10 10:55:14
|
On Wed, 9 Oct 2002, David Goodger wrote:
> Engelbert Gruber wrote:
> > i am willing to give support for real problems, meaning not the
> > pathologic test.txt.
>
> I've got to call you on this one. "Pathological"?!? That is a gross
:-))))
> misrepresentation. The tools/test.txt file is pretty complete (*not*
> 100% though), but there's nothing in it that can't be found elsewhere.
> Certainly nothing pathological!
>
> > sorry my time is limited and there are so much possibilities.
>
> Join the club. ;-)
>
> > maybe we schould split test.txt, so one could get a compliance page,
> > which construct works how good with which writer.
>
> tools/test.txt *is* the compliance file, the only one we've got. I
> don't see a need for a weakened compliance test.
i mean that, test.txt holds "all" constructs as a compliance test
but it does not work (at least not always) when developing, i did
it and julien did the same, he did cut out the hard parts to get
test.txt through the writer.
(i know one might "pass" everything that is not working,
but i am still not sure what writers do in all the places,
e.g. see docinfo handling in latex_writer)
or if i might dare i start making_a_writer.txt in some place
you like and put in what i know and what i donot know ?
i donot want to remove test.txt, but maybe split it so when working
on a feature i can use *the* test-tables.txt file, not do it myself
everytime. and test.txt is the concatenation of all the test-*.txt files.
>
> As I've said before, to get out of the sandbox the LaTeX Writer
> doesn't have to handle every construct perfectly, but it *does* have
> to handle every construct without (a) crashing or (b) silently
> omitting data. If the Writer can't handle a particular construct,
> have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
> output a simpler form, such as the string returned by the
> ``.astext()`` node method. I earlier objected to the presence of many
> Writer/Visitor methods containing only "pass", which is not
> acceptable.
>
> Errors should never pass silently.
> Unless explicitly silenced.
agree absolutely. but it would make life easier if someone really needs
the features (xp-wise nothing would be done otherwise), because the
"customer" is a reviewer with high interest.
about the quickref.html to rest:
either use w3m -dump so one might have the tables useable
(external references are lost maybe link or netkit could do better)
>
cheers
--
BINGO: objects, objects, objects (r.racko)
--- Engelbert Gruber -------+
SSG Fintl,Gruber,Lassnig /
A6410 Telfs Untermarkt 9 /
Tel. ++43-5262-64727 ----+
|
|
From: David G. <go...@us...> - 2002-10-11 03:22:32
|
Engelbert, would you please add some blank lines before & after your
comments? It's difficult to notice your comments without them.
> (i know one might "pass" everything that is not working,
> but i am still not sure what writers do in all the places,
> e.g. see docinfo handling in latex_writer)
I don't see the problem. It should be easy to put in a simple
catch-all method for unimplemented nodes. Just make sure it doesn't
act (or not act) silently. If you're not sure what should be done,
say so explicitly.
> or if i might dare i start making_a_writer.txt in some place
> you like and put in what i know and what i donot know ?
Yes, that would be most welcome. I see that you've already started;
great!
> i donot want to remove test.txt, but maybe split it so when working
> on a feature i can use *the* test-tables.txt file, not do it myself
> everytime. and test.txt is the concatenation of all the test-*.txt
> files.
I see what you're saying now. Incremental testing is definitely
useful; that's how the Docutils test suite works. The parser would
never have been completed without many small unittests (now at 518
tests!).
If you'd like to make up a bunch of small document fragments for test
purposes, go ahead. Perhaps in a new docutils/test/fragments
directory.
>> As I've said before, to get out of the sandbox the LaTeX Writer
>> doesn't have to handle every construct perfectly, but it *does* have
>> to handle every construct without (a) crashing or (b) silently
>> omitting data. If the Writer can't handle a particular construct,
>> have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
>> output a simpler form, such as the string returned by the
>> ``.astext()`` node method. I earlier objected to the presence of many
>> Writer/Visitor methods containing only "pass", which is not
>> acceptable.
>>
>> Errors should never pass silently.
>> Unless explicitly silenced.
>
> agree absolutely. but it would make life easier if someone really
> needs the features (xp-wise nothing would be done otherwise),
> because the "customer" is a reviewer with high interest.
I don't understand what you mean.
--
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: David G. <go...@us...> - 2002-10-10 03:00:53
|
Aahz wrote:
>>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>>> figure 3.11"), how do I do that?
>>
>> I don't know. Currently, figures don't have any attribute which can be
>> referenced. Perhaps a "name" option on figures? For example::
>>
>> .. figure:: image.png
>> :name: image's name
I've thought some more about this (full details soon to appear in the
spec/notes.txt file), and I think the best way to name an object is the
way we've always named targets::
.. _figure name:
.. figure:: image.png
This applies equally well to tables.
>> How to refer to a figure though? Perhaps something like this::
>>
>> See :figure:`image's name`.
I also toyed with the idea of parameterized substitutions::
See |figure (figure name)|, on |page (figure name)|.
.. |figure (name)| figure-ref:: (name)
.. |page (name)| page-ref:: (name)
The result would be::
See figure 3.11 on page 157.
But this would require substitution directives to be processed at
reference-time, not at definition-time as they are now. Or,
the directives could just leave ``pending`` elements behind, and the
transforms could do the work. How to pass the data through?
Too complicated. The original interpreted text approach is better::
See :figure:`figure name` on :page:`figure name`.
The "figure" and "page" roles could generate some boilerplate text.
The position of the role (prefix or suffix) could also be utilized.
>>> I'm probably going to create some kind of ToC directive that goes
>>> in an include file so I can create cross-chapter references
>>> easily.
>>
>> I don't follow.
...
> What I'm thinking more of (at least for starters) is an
> extremely simple list of references to reST documents.
Can you elaborate with details of the file's contents, and ideas of
how it would work? I'd like to understand what you're proposing (and
I don't have a clue now).
--
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: Aahz <aa...@py...> - 2002-10-10 04:27:58
|
>>>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>>>> figure 3.11"), how do I do that?
>>>
>>> I don't know. Currently, figures don't have any attribute which can be
>>> referenced. Perhaps a "name" option on figures? For example::
>>>
>>> .. figure:: image.png
>>> :name: image's name
>
> I've thought some more about this (full details soon to appear in the
> spec/notes.txt file), and I think the best way to name an object is the
> way we've always named targets::
>
> .. _figure name:
>
> .. figure:: image.png
>
> This applies equally well to tables.
It's not clear to me how these two directives interact.
> Too complicated. The original interpreted text approach is better::
>
> See :figure:`figure name` on :page:`figure name`.
>
> The "figure" and "page" roles could generate some boilerplate text.
> The position of the role (prefix or suffix) could also be utilized.
That works for me.
>>>> I'm probably going to create some kind of ToC directive that goes
>>>> in an include file so I can create cross-chapter references
>>>> easily.
>>>
>>> I don't follow.
>>
>> What I'm thinking more of (at least for starters) is an
>> extremely simple list of references to reST documents.
>
> Can you elaborate with details of the file's contents, and ideas of
> how it would work? I'd like to understand what you're proposing (and
> I don't have a clue now).
First the ToC::
.. ToC-list::
Introduction.txt
Objects.txt
Data.txt
Control.txt
Then a sample use::
.. include:: ToC.txt
As I said earlier in chapter :chapter:`Objects.txt`, the reference
count gets increased every time a binding is made.
Which produces::
As I said earlier in chapter 2, the reference count gets increased
every time a binding is made.
The ToC in this form doesn't even need to be references to actual reST
documents; I'm simply doing it that way for a minimum of future-proofing,
in case I do want to add the ability to pick up references within
external chapters.
--
Aahz (aa...@py...) <*> http://www.pythoncraft.com/
Project Vote Smart: http://www.vote-smart.org/
|
|
From: Richard J. <rj...@ek...> - 2002-10-10 04:45:53
|
On Thu, 10 Oct 2002 2:25 pm, Aahz wrote:
> David wrote:
> > I've thought some more about this (full details soon to appear in the
> > spec/notes.txt file), and I think the best way to name an object is the
> > way we've always named targets::
> >
> > .. _figure name:
> >
> > .. figure:: image.png
> >
> > This applies equally well to tables.
>
> It's not clear to me how these two directives interact.
The ".. _figure name:" creates a target, placing a target called "figure name"
in the document just before the ".. figure::" directive. Not entirely clear,
no, and I'd actually prefer the
.. figure:: image.png
:name: figure name
which looks a lot clearer (in terms of keeping related information together)
to me as a document author. I've always seen the ".. _figure name:" target
generation syntax as a last-resort fallback, as it's almost always jarring to
see in the source text. But that could just be me :)
Richard
|
|
From: Aahz <aa...@py...> - 2002-10-10 04:50:05
|
On Thu, Oct 10, 2002, Richard Jones wrote: > On Thu, 10 Oct 2002 2:25 pm, Aahz wrote: >> David wrote: >>> >>> I've thought some more about this (full details soon to appear in the >>> spec/notes.txt file), and I think the best way to name an object is the >>> way we've always named targets:: >>> >>> .. _figure name: >>> >>> .. figure:: image.png >>> >>> This applies equally well to tables. >> >> It's not clear to me how these two directives interact. > > The ".. _figure name:" creates a target, placing a target called > "figure name" in the document just before the ".. figure::" > directive. Not entirely clear, no, and I'd actually prefer the > > .. figure:: image.png > :name: figure name > > which looks a lot clearer (in terms of keeping related information > together) to me as a document author. I've always seen the ".. _figure > name:" target generation syntax as a last-resort fallback, as it's > almost always jarring to see in the source text. But that could just > be me :) +1 reST should be easy to read for people only minimally familiar with it. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
|
From: David G. <go...@us...> - 2002-10-11 01:54:32
|
[David]
>>>> I've thought some more about this (full details soon to appear in
>>>> the spec/notes.txt file), and I think the best way to name an
>>>> object is the way we've always named targets::
>>>>
>>>> .. _figure name:
>>>>
>>>> .. figure:: image.png
>>>>
>>>> This applies equally well to tables.
[Aahz]
>>> It's not clear to me how these two directives interact.
The first isn't a directive.
[Richard]
>> The ".. _figure name:" creates a target, placing a target called
>> "figure name" in the document just before the ".. figure::"
>> directive. Not entirely clear, no, and I'd actually prefer the
>>
>> .. figure:: image.png
>> :name: figure name
>>
>> which looks a lot clearer (in terms of keeping related information
>> together) to me as a document author.
I can see your point of view.
>> I've always seen the ".. _figure name:" target generation syntax
>> as a last-resort fallback,
Yes, I suppose it is.
>> as it's almost always jarring to see in the source text. But that
>> could just be me :)
No, I try to avoid them as well. They add clutter.
[Aahz]
> +1
>
> reST should be easy to read for people only minimally familiar with
> it.
Agreed, and convinced. I was trying for something that would be
applicable to tables as well, but that can be done easily with a
simple wrapper directive::
.. table:: optional title here
:name: table's name for references here
===== =====
x not x
===== =====
True False
False True
===== =====
This would also allow other attributes to be set, like border styles.
The same technique could be used for other objects.
--
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: Richard J. <rj...@ek...> - 2002-10-11 02:00:53
|
On Fri, 11 Oct 2002 11:58 am, David Goodger wrote: > Agreed, and convinced. I was trying for something that would be > applicable to tables as well, but that can be done easily with a > simple wrapper directive:: > > .. table:: optional title here > > :name: table's name for references here > > ===== ===== > x not x > ===== ===== > True False > False True > ===== ===== I just saw this go past in the CVS log, and I _like_ it :) +1 Richard |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X