[Doc-SIG] Re: rest-mode.el and more

[David Goodger]

[Stefan Merten]
 >>> * Is there a Emacs mode already?

[David Goodger]
 >> Not yet.  There are a few functions in
 >> tools/editors/emacs/restructuredtext.el, available from CVS or the
 >> snapshot (<http://docutils.sf.net/docutils-snapshot.tgz>).

[Stefan Merten]
 > Yes. This could and should be integrated with my work then.

Indeed.  I think basing a custom mode on indented-text-mode would be a
good place to begin.  Although I hack elisp functions, I've never
tackled a mode.

 > I coded a font-lock mode which recognizes most reST constructs.

It looks quite good!  I hope you continue to develop it.

Could it be made a derivative of indented-text-mode, so that it
inherits that mode's behavior?  Or is it already, except for keymaps?
(How does one tell?)  Or could this become a minor mode of
indented-text-mode?

 > If you want to include it in an official CVS tree that's fine.

Thank you.  I think I'll include it as tools/editors/emacs/rst-mode.el
("rst" not "rest", see below).

 > Please note that in the file I'm suggesting file name extensions
 > ``.rest`` and ``.reST`` for reStructuredText documents. I don't know
 > whether there is a widely accepted extension already. However, I
 > think there should be one.

See the discussion at <http://docutils.sf.net/FAQ.html>, questions 2.3
& 2.4.  I think .rst would be preferable to .rest, for length and to
distinguish it from the other REST.  Personally, I'll never use a .rst
or .rest extension on files, only .txt, so the auto-mode-alist will
not be useful to me.  I may just set my default major mode to rst-mode
in my .emacs file; it's now set to indented-text-mode.

 >>> * Are there writers for plain text and/or manual pages?
...
 > Hmm... While thinking about it: It would suffice to have a writer
 > for POD. This way you'll indirectly have a writer for manual pages
 > for free.

The same is true of DocBook, since it can generate man pages.  But
either one means that an external tool is needed.

 >>> Finally I'd like to draw your attention to
 >>>
 >>>     http://template-toolkit.org/
[... and SDF ...]
 >> Sounds like "literate programming".  Do you have a link to a
 >> description of how SDF accomplishes this rearranging?
 >
 > This was solved fairly easy. The extractor (``sdfget``) used a table
 > like this::
...

Thanks for the explanation.  Something similar to SDF or the template
toolkit might be feasible with reStructuredText directives in a
template file.  It's worth exploring, and other literate programming
systems may have ideas we can use.  I'd like to see any resulting
system be as simple and intuitive as possible, and be able to use all
information already marked up explicitly or identified implicitly in
the source (such as bibliographic fields such as "author").

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv