[Doc-SIG] Comments on "inline external targets" example texts

[David Goodger]

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
readers.

>> 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  <goodger@users.sourceforge.net>  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/