[Doc-SIG] Comments on "inline external targets" example texts
Fri, 26 Jul 2002 22:54:14 -0400
Paul Moore wrote:
> The insight I had in looking at these was that the *maintainer*
> needs to read the plaintext, even if no-one else does. And virtually
> nothing which gets published ends up with only one maintainer...
Good point. The authors/maintainers of a document are also among its
>> Indeed, the "Gimp Links" example offers the only hope for
>> redemption for the feature. That style of "list of links"
>> document lends itself to inline external targets.
> A suggestion I made before, but badly, may be relevant here. If you
> can define a syntax specifically for "list of links" type of
> documents, could you not use a custom directive? For the Gimp
> example, suppose I write a link-list directive, which takes a series
> of entries, each of which contains a link, followed by '--',
> followed by free text, and formats it as a list of links, any way
> the directive writer prefers.
> Does this example make my suggestion any clearer? I may have some of
> the details wrong, as I've never really looked at custom
> directives. But basically, the idea is to abstract out the concept
> of a "list of links" and code it directly.
Thanks for the re-statement. In context, I get it now! Your
directive would implement a very specific case (bullet lists of
links), but we can extract the underlying idea (which is a basic idea
of directives). By using a directive, we can force a local implicit
syntax interpretation different from the global one, and thus reduce
the explicit syntax required. I don't know if it's general enough to
satisfy Simon, but it may have potential.
As I was visiting Slashdot.org just now, I realized that inline
external targets would be very useful for blogs, which are
stream-of-consciousness, written once but read often (in processed
form only). I can see places where this would be useful, but I want
to prevent abuse, somehow, if possible.
David Goodger <email@example.com> 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/