[cl-faq] Format & editorship (and outline mode), Re: Now, with less over-engineering!!

[Peter Seibel]

On Jan 15, 2006, at 10:26 AM, Matthew Astley wrote:

> On Sun, Jan 15, 2006 at 06:29:53AM +0100, Pascal Bourguignon wrote:
>> Peter Seibel writes:
>
>>> As I started to think about actually editing the FAQ I came to my
>>> senses and realized that I was completely missing the point of my
>>> own Markup library with that \faq{\question{...}\answer{...}}
>>> nonsense.
>
> Or...  you saw a better way and switched to it without losing any
> data?

Yes. I converted from two different Markup-based structures. The data  
is all still there. So if you submitted questions in the past, they  
should still be in the FAQ, assuming I ever added them.

>>> So I wrote some code to dump the file out in a more normal Markup
>>> form, taking advantage of the support for Emacs outline mode, etc.
>
> Outline mode is your friend, yes.  C-2 C-c C-q especially.
>
> (:offtopic Anyone use it for Lisp source?  You can redefine the
> regexps.  I did one for pbook mode.  C-2 C-c C-@ C-q is then handy.)

Not for Lisp source. But I played around with redifining the regexps  
while working on my book and discovered that you really want to make  
sure you use *efficient* regexps. ;-) Eventually I gave up on that  
and realized it'd be easier to make my homebrew typesetting system  
grok the regular outline markers. And thus was born Markup.

>> This sounds insufficient, if we judge from the old FAQs.
>
> I agree that it may be useful to have extensions.  The problem with
> putting the whole Q on the star-heading line is that you're limited to
> small questions that don't use blockquote.

That's true. On the one hand, I don't want to be limited by our  
tools. On the other hand, there's part of me that thinks the  
constraint (whether due to our tools or just by agreeing to live by  
it) of having short questions has some other advantages. For  
instance, you can usefully use the questions as a table of contents  
which gets harder if you need a whole paragraph just to ask the  
question. I think of it sort of like operating within the constraints  
of a poetic form (haiku, sonnet, whatever.)

However, feel free to submit questions that don't really fit on one  
line if you want and maybe I'll be convinced that there are questions  
that must be that long?

> I do wonder, what is the meaning of
>
>   ** level2
>   *** level3
>   text
>
> Is level2 a question with no answer, or just a heading?  And what if
> there were text between the two headings?

It's a section heading. Text between a ** heading and *** question  
would be emitted as regular paragraphs and could be used to introduce  
the section or whatever.

>> there's a lot of _urls_, even for book references (thanks to
>> Amazon).
>
> Auto URL highlighting would be handy.  Presumably it's a SMOP, at
> least for HTML output?

Well, the Markup solution is to wrap urls in \url{...} and then we  
can emit them however we want. At the moment they are emitted in HTML  
as a link to the URL with the text of the URL as the link text. If  
you want to make links with other link text use \link{\href{url}\text 
{whatever}}. I'm not crazy about that and am thinking about some way  
to express that more nicely. Maybe even something as simple as \link 
{url text} since, IIRC, URI's can't contain enencoded spaces.

Another handy markup tag is \cl{...} which I put around names that  
are referring to symbols in the COMMON-LISP packagge. At the moment I  
just render them specially (bold and code font) but when I get around  
to it, I'll make them render as links to the appropriate page of the  
hyperspec.

>> Christophe Rhodes used Docbook to generate his lispfaq.html.
>> Perhaps we should use a sexpr markup?  But do we need to generate
>> several formats?
>
> Noting Peter's explanation,
>
> | Markup *is* a sexp markup system. It just happens to have a surface
> | syntax that is easier to edit as plain text than raw sexps would be.
>
> One thing that's potentially useful is roundtripping.  The current
>
>   Markup -> sexp -> (PDF HTML RTFmaybe)
>
> was chosen because it is convenient for the current editor.
>
> Contemporary contributors can like it or suggest a mutually acceptable
> alternative and assist with migration.
>
> Subsequent FAQ maintainers, possibly including ourselves, may find it
> handy to be able to do some of
>
>   sexp -> (Markup LML2 Docbook)
>
>   Docbook -> sexp -> Markup
>
> and in theory this should be do-able.

In practice the sexp -> Markup stage is already doable. That's how I  
converted from the previous to current format--suck it in with Markup  
and dump it back out after munging the sexps some.

> Whether it's worth the effort
> is a choice for the gardener of the day.  sexp seems to be the obvious
> hub element, both for practical and dogfood-eating reasons.

Yes.

> I'm just hoping to demonstrate that roundtripping of (an adequate
> subset of) whatever we _do_ use will tend to make discussions of "what
> format should we use?" something of a non-event.

Yes.

-Peter

-- 
Peter Seibel           * peter at gigamonkeys.com
Gigamonkeys Consulting * http://www.gigamonkeys.com/
Practical Common Lisp  * http://www.gigamonkeys.com/book/