Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

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