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

[Matthew Astley]

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?

> > 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.)

> > Anyone, who's got questions and answers in the old form should
> > send them along; I'll deal with converting them.

I have what I posted earlier, but I suspect it suffers an excess of
enthusiasm over careful thought.  I'll deal with submitting it again
later.


> > But for future the format is much simpler:
> > 
> >    *** Question text here, all one one line.
> > 
> >    Answer here using Markup conventions [...]

> 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.

One way round this would be (whole thing further indented by two for
clarity),

  ** I have a problem with `foo'.  I wrote
  \moreq{
    (defun wibble ()
      (foo 'wrong-stuff))

  and it ate my lunch.  What happened?}

  Because `foo' is a heptofump, it should be passed a string not a
  symbol.

  \answer

  In modern Lisps you can use `bar' instead of `foo', and this accepts
  a symbol or a string.

So we have extension of question past the header line, which is likely
to be handy sometimes but in general may indicate a too-long question.

Any text under the heading that isn't in \moreq{} is the (first)
answer.  There's also a low-markup way to separate the "Q: A1: A2:"
cases.

A variation (which doesn't mix well with the other),

  ** I have a problem with `foo'.  I wrote >>>

    (defun wibble ()
      (foo 'wrong-stuff))

  and it ate my lunch.  What happened?

  \answer

  Because `foo' is a heptofump, it should be passed a string not a
  symbol.

  \answer

  In modern Lisps you can use `bar' instead of `foo', and this accepts
  a symbol or a string.

so the text inside the heading is question-continuation or answer,
depending on the end of the header.  I guess >>> would translate as a
newline in the question, and likewise a newline in the question can be
translated back into this format.


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?


> 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?

> 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.  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.


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.


> To edit it in a collaborative effort, I feel that a wiki would be
> easer.  What about the wikipedia format? [...]

If you had wikipedia <-> sexp gateway code of any sort, you could
freely do your own editing on the wiki and submit patches back in
Markup format.

As well as the format change, Wiki brings the organisational change
which may not be compatible with having an official FAQ editor...?


[snip big Q list]

Probably a topic for another thread?


Matthew  #8-)