Mailing List Archive: 49091 messages

## [REBOL] Re: Make-Doc Formatter replaces Make-Spec

### From: carl:rebol at: 25-May-2001 16:47


At 5/26/01 09:02 AM +1200, you wrote:
>Carl wrote:
> > Make-Doc is a two pass text formatter. The first pass converts to a REBOL
>block format. The second pass uses that block format to convert to the
>output target format, which is HTML at this time, but it could be any type
>of output, including Text, PDF, Tex, Helpfiles, .roff, whatever you want.
>
> > Writing the output formatters is fairly easy... you can use the HTML
>version as an example.  Eventually we will want to put the output formatters
>in separate files.
>
>I thought this:
>         "#" paragraph opt newline (emit enum para) |
>     was a interesting idea for numbered lists (as a non-American I'm not
>familiar with the use of "#" as meaning "number". I've been using "0" (the
>digit/character zero) as the marker, followed by a tab.

The # is pretty standard for "number" in American. Funny how things like that are not
international, eh?

>This:
>         \in
>     and:
>         /in
>     seems intrusive, for signalling indents. I prefer to use tabs for this
>purpose.

Tabs indicate code sections. E.g.:

This is a section of code.

The reason: code sections are much more frequently
used than indents for the type of documents that we
produce.  We have a lot of code examples, so this
makes it easier.  I'm not sure that we've ever
used an indented section.  They are there just in
case.

>I'm a little disturbed by lines like:
>         h2: <font face="arial,helvetica" size="3">
>     as I'm a current fan of using style sheets. But I can see the advantages
>of having one file containing all the formatting.

You can probably still use style sheets, this approach is just the standard for our documents.
This information is specified on the output side of Make-Doc, so change it to match
whatever style you desire. Check that it works on every browser.

>         emit-toc: func [doc /local w] [
>     I'm currently prefering to create fine-grained, massively hyperlinked
>document sets, with a Rebol script that links them all together and
>automatically creates tables of contents, indexes and reverse indexes for
>me.

Yes, that sounds great, Symbolics used to do that for their docs... and it can be very
helpful.  But, that is not the initial purpose of Make-Doc.  Make-Doc is a simple solution
to allow us to create documents quickly.

Read the make-spec file in the docs folder for more about it. There is a new doc for
Make-Doc, but it's not posted as of yet.  This weekend, I hope.