[Docutils-develop] Self-documenting errors (was: Re: [Docutils-users] docutils for windows)

[Beni C. <cb...@us...>]

[moving to the develop list, since I want to discuss petty
implementation questions and it's no longer informative to the OP]

2008/4/24, David Goodger <go...@py...>:
> On Thu, Apr 24, 2008 at 10:39 AM, Kaushal Shriyan
>  <kau...@gm...> wrote:
> > I am getting
>  >
>  > C:\>docutils\tools\rst2html.py mysqlmasslavdocs.txt mysqlkrs.html
>  > mysqlmasslavdocs.txt:95: (WARNING/2) Literal block ends without a blank
> > line; unexpected unindent.
>  ...
>
>  Literal blocks must be indented relative to the line containing the "::".
>  http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks
>  http://docutils.sourceforge.net/docs/user/rst/quickstart.html#preformatting-code-samples
>  http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks
>
It'd be best if docutils itself could detect FAQ issues and point
people at the relevant places in the documentation.  This is an
example of a situation which can easily be detected: it's not just any
unexpected unindent, it's an unindent right after the ``::`` -- which
very probably indicates that the user misunderstood the syntax of
literal blocks.

So I'm going to implement an extended message for this case.  (I'm too
lazy for a directed effort to add such messages in all possible
places, but one message at a time will also eventually help.)

Points I want to get advice on:

* Should the messages try to be self-contained or just point to the docs?
  I think a pointer is needed, and more than a sentence

* Should the pointers be to docutils.sf.net or to a local copy?
  Can we assume at all that a local copy is installed along with docutils?
  Can we guess its location with any degree of reliability?

  *  If we *want* to be able to use a local copy, we should probably
take it's address as a configuration (defaulting to sf.net), so that
distributions can set it in ``/etc/docutils.conf``.

* Should I bother pretty links in the errors as they appear in the HTML?
  Assuming a URL will be automatically linked (will check), I think not.

* What document(s) should we reference?
  The FAQ / quickstart / quickref / full reference?
  Since the quickstart links to the quickref which links to the full
reference, I think just one link (to the most user-friendly doc that
cover the issue) in the error message is enough.

* Should I be concerned about URL stability?
  Basically, I think not - we've been linking to sections of these
docs for a long time and they remained stable.
  But perhaps adding some name aliases (in this case in
quickstart.html: #literal-blocks -> #preformatting-code-samples) would
help.

-- 
Beni Cherniavsky <cb...@us...> (I read email only on weekends)