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

[will]

My comments on the comments inline...

> David Goodger (goodger@users.sourceforge.net) wrote:
> > It comes down to this: the top goal of reStructuredText is to be as readable
> > in plaintext (source) form as in processed form.  An important market for
> > this is (will be) Python docstrings.  You and Simon seem not so interested
> > in the plaintext readability issue; it's the processed output which is most
> > important.
> 
> On Wed, 3 Jul 2002, Simon Budig wrote:
> 
> Yes, this is an important point, but easy edit-ablity (?) is also very
> important. There are enough complicated markup languages out there,
> and reST is the easiest I have came across (with the exception of
> some other textual markup languages that fail to have some kind of
> sane specification).

I have an open source project which is all coded in Python.  Currently we
use StructuredText for all our docstrings (which I border on loathing for
various reasons) and we used to use AFT for our manuals.  I switched all
the manual stuff from AFT to reStructuredText a week or two ago in the
space of two hours without much effort.

I include the actual reST source of the manual text with our source
code--it all comes in one big bundle.  So it's important that users can
read the manual without having to convert it to some readable format.  
reST is perfect in this case.  My developers are happy, my users are
happy, and I'm happy.  No one seems to have a problem understanding the
text even though they don't know the specifics of reST markup.

Then I convert the manuals to HTML for the web-site along with the
doc-string docs from HappyDoc and various other things we maintain on the
web-site.

My experiences with reST so far lead me to believe that it's very well
thought out, it's very readable, it's easy to maintain (with the exception
of tables, but like David said, tables are going to be difficult to
maintain whichever way you slice it), and I can convert it to other
formats for other mediums.

I've been on this list for some time.  It has never been a goal for reST
to **only** be used for doc-strings.  In fact, it's been suggested several
times that we use reST as the unifying markup for all of Python's
documentation.  So that's specifically what reST was built around.

There will be a series of things for which reST markup is a good tool and
a series of things where it's going to be terrible.  I don't think any of
us disagree on this point.

Personally, I think you're crazy to use reST with SSI and whatever else to
build your web-site.  I think it'd be much easier for you, especially if
you hate HTML, to get a wysiwig editor and build it with that.  The
Mozilla composer (or whatever it's called) is pretty good and the html it
produces isn't that crappy.  You could always run the composer HTML
through tidy which will fix up a lot of things.  Does that mean you
shouldn't do it?  No.  But you don't see people writing RDMS database
servers in Befunge either.


> On Wed, 3 Jul 2002, Simon Budig wrote:
> 
> 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.

reST can't be all things to all people.  It's simply not possible.  Just
as there's no single spoken language in all the world.  From that we 
derive that we have to pick the applications that we want reST to be 
really good at and if people find other applications for reST, then that's 
way cool, but it shouldn't change our mission.

In that vein, reST is definitely not the syntax I would use for building
web-sites where the user doesn't understand what they're doing.  You're
just replacing one verbose formatting markup language (HTML) for another
non-formatting markup language which is not verbose and uses a lot of
punctuation because we're interested in the source being readable.

In either case, the secretary is going to have to learn a markup language.  

So my bottom line is that unless you really have something that's a
clincher for an argument one way or another about the links, I vote we
table this dicussion possibly ad infinitum.  Though it would be
interesting to get some input from other people using reST.

/will

-- 
whatever it is, you can find it at http://www.bluesock.org/~willg/
except Will--you can only see him in real life.