Re: Schemey markup (was Re: Doc Tasks)

[Lalo Martins <lalo at webcom dot com>]

On Mon, Dec 27, 1999 at 10:40:01PM +0200, Michael Livshin wrote:
> Lalo Martins <lalo@webcom.com> writes:
> 
> > Hmm. Or of course you could write proper Scheme and quote
> > strings. Then of course you'd want parens, because you're
> > already used to them if you're working on Guile.
> 
> no, I don't thing so.  at least to me, writing a docstring works like:
> I write a string, and escape out when I want to mark something up.

Ok, I did some more thinking based on a real example lifted from previous
posts to this list. Here is what I propose to be used for docstrings inside C
code (docstrings in scheme would look different):

--- start ---
GUILE_PROC(scm_substring_move_x, "substring-move!", 5, 0, 0,
           (SCM str1, SCM start1, SCM end1, SCM str2, SCM start2),

"Copy the substring of #(param str1)# bounded by #(param start1)# and
#(param end1)# into #(param str2)# beginning at position #(param end2)#.
#(code substring-move-right!)# begins copying from the rightmost character
and moves left, and #(code substring-move-left!)# copies from the leftmost
character moving right.

It is useful to have two functions that copy in different directions so that
substrings can be copied back and forth within a single string.  If you wish
to copy text from the left-hand side of a string to the right-hand side of
the same string, and the source and destination overlap, you must be careful
to copy the rightmost characters of the text first, to avoid clobbering your
data.  Hence, when #(param str1)# and #(param str2)# are the same string,
you should use #(code substring-move-right!)# when moving text from left to
right, and #(code substring-move-left!)# otherwise.  If #(param str1)# and
#(param str2)# are different strings, it does not matter which function you
use.")

#define FUNC_NAME s_scm_substring_move_x
{
--- end; function code follows ---

From that, the extractor would produce something like:

(gdoc-function #:name "scm_substring_move!"
#:parameters (gdoc-parameters 'str1 'start1 'end1 'str2 'start2)

"Copy the substring of" (gdoc-param "str1") "bounded by" (gdoc-param "start1") "and"
(gdoc-param "end1") "into" (gdoc-param "str2") "beginning at position" (gdoc-param "end2") "."
(gdoc-code "substring-move-right!") "begins copying from the rightmost character
and moves left, and" (gdoc-code "substring-move-left!") "copies from the leftmost
character moving right.

It is useful to have two functions that copy in different directions so that
substrings can be copied back and forth within a single string.  If you wish
to copy text from the left-hand side of a string to the right-hand side of
the same string, and the source and destination overlap, you must be careful
to copy the rightmost characters of the text first, to avoid clobbering your
data.  Hence, when" (gdoc-param "str1") "and" (gdoc-param "str2") "are the same string,
you should use" (gdoc-code "substring-move-right!") "when moving text from left to
right, and" (gdoc-code "substring-move-left!") " otherwise.  If" (gdoc-param "str1") "and"
(gdoc-param "str2") "are different strings, it does not matter which function you
use.")

Which is honest and working Scheme code (assuming you define
all the ``gdoc-*'' procedures). Now to render it into some
other format you just load some ``gdoc'' (or something) module
and execute the whole markup. Perhaps all you need for
different outputs is to have (doc gdoc html) (doc gdoc texi)
(doc gdoc DocBk) modules. Get my point?


> my main point was that the markup (whatever syntax it may use) should
> have the right *semantics*.  as far as syntax goes, my main objection
> to *ML is that it's kinda hard on the eyes and wrists.

Yes. This kind of markup is a little (not a lot, I'm afraid)
easier on wrists and a lot better on eyes (at least for
Schemers).

> > That would require that all tags are implemented as procedures,
> > with options as keywords and everything else as a list. Then
> > the final presentation generators have to come up with a smart
> > string concatenation method and voila.
> 
> I'm not sure I understand this.  the presentation generators have to
> map Guile semantic tags to target tags, in many cases lossily, which
> is hardly string concatenation.  can you explain?

I'm thinking of having the extraction result on a Scheme script
you can just execute (only needing to preload the correct
output module).

[]s,
                                               |alo
                                               +----
--
      I am Lalo of deB-org. You will be freed.
                 Resistance is futile.

http://www.webcom.com/lalo      mailto:lalo@webcom.com
                 pgp key in the web page

Debian GNU/Linux       ---       http://www.debian.org
Brazil of Darkness   --   http://zope.gf.com.br/BroDar