[Doc-SIG] References in the same line as the target text

[David Goodger]

Simon,

I don't have time to answer all of your points right away, but I can
quickly respond to some of them.

Simon Budig wrote:
> It is in my eyes a great pity that you seem to have a tendency to
> limit reST to the docstring-scope.

Nothing could be further from the truth!  Although a major goal is to
get docstring processing working, and it will be a major part of the
project, take a look at the project right now: docstring processing is
not yet part of the core.  Tony Ibbs has a preliminary prototype in
the sandbox, but that's it.  The only working part of the project now
is geared toward producing web pages!  And there's plenty of room for
improvement, which would be quite welcome.

Just because I'm not accepting the ``reference_(URL)`` syntax, doesn't
mean reStructuredText is anti-HTML.  Simply put, that syntax just
doesn't fit with the rest of reStructuredText.  Please don't confuse
unrelated issues.

[Referring to http://docutils.sf.net/index.txt, source of
http://docutils.sf.net/index.html:]
> Just to show the uglyness of anonymous and named links: This is from
> the webpage source (as in CVS):

Yes, the source to that web page is not pretty.  It was written in a
lazy manner, using many anonymous hyperlinks.  But that's OK, because
this is an example of a document where only the HTML is meant to be
seen.  The source is *not* intended to be read by anyone but me or
other project developers.  That file is not distributed with the
project code or documentation.  It is not given as a model for good
reStructuredText usage.  Also, being a home page, it is complex and
full of external links, much more so than a typical document.

> Please don't try to tell me that a newbie easily finds the URL for
> `Docutils CVS repository`__

Sorry to burst your bubble, but I think it would be *very easy* for a
newbie to find the URL.  They just click on the text "Docutils CVS
repository" on the HTML page, and their browser takes them there.  No
newbie would ever be exposed to the source text. (This is a poor
choice to single out as a poor example. ;-)

will (willg@bluesock.org) wrote:
>> Personally, I think you're crazy to use reST with SSI and whatever
>> else to build your web-site.

I don't think it's crazy; the Docutils web site is built with
reStructuredText/Docutils and I intend for this functionality to
become more sophisticated.  I agree with Simon when he wrote:

[Simon]
> I think that there really is a need for a simple markup language
> that can be used by - for example - a secretary to maintain a simple
> Website. HTML fails the "understandable to non-geek-guys"-test,
> GUI-tools are known to produce crappy HTML code when used by
> non-experts.
> 
> reST really could fill a gap here.

And that's one of the things it's already doing, and pretty
successfully I think.  Of course there's room to grow.

> Just to show you what is possible with SSIs and why I think using
> reST for webpages is not crazy:
> 
> Have a look at http://www.home.unix-ag.org/simon/bsdaemon/

Apart from the extras pulled in through server-side includes, the page
is very simple, nothing that reStructuredText couldn't handle.

> The raw source of it is::
> 
>    <!--#include virtual="$SCRIPT_NAME/../../include/head_start.shtml" -->

A server-side include directive could be added to reStructuredText, no
problem.  Although I'm very careful about new *syntax*, new directives
are much easier to let in, because they're explicit and typically
don't require new syntax (and if they do, it's localized and
*explicit*).

...
>    <img src="bsdaemon.png" alt="Preview of the BSD Daemon" align="right"
>    width="326" height="352"><p>

I've thought of adding support for more image attributes, like
"align".  Care to try?

> I think it should be fairly trivial to create such an output with
> reST

I agree, as long as the fancy graphical layout elements don't have to
be reStructuredText.  That's what stylesheets and server-side includes
are for.

-- 
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/