Make-Doc Formatter replaces Make-Spec
[1/10] from: carl::rebol::com at: 25-May-2001 12:05
Make-Doc, the next generation of Make-Spec, has been posted
to the library. You can find it in the Text or HTML folders.
This is an ALPHA test version, a work in progress. However, it
will format many of the prior make-spec docs at this time.
The 1.0 will be released this weekend, if all goes well.
All future REBOL documentation will use this converter.
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.
-Carl
[2/10] from: m:koopmans2:chello:nl at: 25-May-2001 22:38
Carl,
I get my source file in HTML, no function overview? Is that intentionally?
Will object (hierarchies) also be documented?
Thanks,
Maarten
[3/10] from: al:bri:xtra at: 26-May-2001 9:02
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.
This:
\in
and:
/in
seems intrusive, for signalling indents. I prefer to use tabs for this
purpose.
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.
Instead of:
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.
BTW, in case people have difficulties, the make-doc file is at:
www.reboltech.com/library/scripts/make-doc.r
Andrew Martin
ICQ: 26227169 [new Rebol/eText site soon!]
[4/10] from: carl:rebol at: 25-May-2001 16:33
What source file? Make-doc.r?
At 5/25/01 10:38 PM +0200, you wrote:
[5/10] 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
<<quoted lines omitted: 9>>
>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.
>Instead of:
> 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.
[6/10] from: allenk:powerup:au at: 26-May-2001 18:23
----- Original Message -----
From: "Carl Sassenrath" <[carl--rebol--com]>
To: <[rebol-list--rebol--com]>
Sent: Saturday, May 26, 2001 9:47 AM
Subject: [REBOL] Re: Make-Doc Formatter replaces Make-Spec
> 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?
How did that usage miss NZ? Quite common in Australia. I guess that prooves
NZ isn't a state of Australia, despite what some poor US cable news
reporters say.
Cheers,
Allen K
[7/10] from: gchiu:compkarori at: 26-May-2001 20:37
On Sat, 26 May 2001 18:23:11 +1000
"Allen Kamp" <[allenk--powerup--com--au]> wrote:
> How did that usage miss NZ? Quite common in Australia. I
> guess that prooves
> NZ isn't a state of Australia, despite what some poor US
I think Andrew speaks only for himself :-)
--
Graham Chiu
[8/10] from: robert:muench:robertmuench at: 26-May-2001 11:18
> -----Original Message-----
> From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
> Carl Sassenrath
> Sent: Saturday, May 26, 2001 1:48 AM
> To: [rebol-list--rebol--com]
> Subject: [REBOL] Re: Make-Doc Formatter replaces Make-Spec
Hi, first I would like to see that some of the ideas from the eText / WebDialect
projects are going to be included into Make-Doc. IMO a single Make-Doc approach,
which is used by RT and the community makes sense. Fragmentation of solutions
isn't our best friend here...
> >This:
> > \in
<<quoted lines omitted: 4>>
> Tabs indicate code sections. E.g.:
> This is a section of code.
What I don't like with the current approach is, that I can't visually structure
my text, as indents have a semantic use. How about something like:
->
This text is indent.
<-
-code-
This is a seciton of code.
-code-
With this I can indent my text as I want, and tell the generator what I want.
> Make-Doc is a simple solution to allow us to create
> documents quickly.
That's why it's very handy. IMO there isn't a lot of formatting needed for most
documents, so we are mostly 80% done, to have a general purpose eText solution.
Andrew, maybe we can extend Make-Doc to Make-Doc/Pro and add some stuff from the
eText project? Robert
[9/10] from: al:bri:xtra at: 27-May-2001 11:01
Robert wrote:
> Carl wrote:
> > Tabs indicate code sections. E.g.:
> >
> > This is a section of code.
>
> What I don't like with the current approach is, that I can't visually
structure my text, as indents have a semantic use. How about something like:
> ->
> This text is indent.
<<quoted lines omitted: 3>>
> -code-
> With this I can indent my text as I want, and tell the generator what I
want.
I prefer using a single tab for start of paragraphs, and double tab for code
sections. For example:
A continuing paragraph, followed by:
print "My rebol script sample." ; An example script.
With a continuing paragraph afterward.
And here's a separate paragraph that shouldn't have a first line indent.
The goal of my eText is that the plain text should be very user friendly and
look like the formatted text, with no explicit markup. Having "-code-" to
indicate code sections or "->" for indents isn't nice, particularly when my
eText script all ready works correctly for the above example and outputs the
correctly formatted HTML code using style sheets, and uses appropriate fonts
with my eText stylesheet.
> Andrew, maybe we can extend Make-Doc to Make-Doc/Pro and add some stuff
from the eText project?
I'll have to add the "#" part for numbered lists.
Andrew Martin
ICQ: 26227169 [new Rebol/eText site soon!]
[10/10] from: al:bri:xtra at: 27-May-2001 22:22
> > Andrew, maybe we can extend Make-Doc to Make-Doc/Pro and add some stuff
from the eText project?
> I'll have to add the "#" part for numbered lists.
And, I'll have to alter my %Index.r site so that names with embedded spaces
use "_" instead of the spaces for file names and HTML links.
Andrew Martin
Picking grape skins from between toes...
ICQ: 26227169 [new Rebol/eText site soon! ^H^H^H^H^H^H later...]
Old wine in new bottle site: http://zen.scripterz.org
Notes
- Quoted lines have been omitted from some messages.
View the message alone to see the lines that have been omitted