World: r3wp

... so what is the aim of make-doc group as posted on rebol.net? 
Will there be any unified version, abstracted, so various output 
formats plus separate styling (e.g. for html) in .css would be possible?

That's the idea...

According to the official project page on rebol.net, Robert is one 
of the members of the Make-Doc standardisation project. So he should 
know.

Ok, I already updated my local docs need to publish them on the server 
as well.

well, so what will be initial make-doc from which we will evolve? 
Make-doc 1.0? 2.5? IIRC MDP evolved from MD 1.0?

the problem is I have various docs here and I don't like reformatting 
for myriads of version just to find out which look better ...

Yes, the thing is to first agree on the markup to use. But we didn't 
make it to get the mentioned people to start working together towards 
one solution.

but - I would definitely vote for =include command - both for code 
and another text file, so you would be able to construct more complex 
docs from smaller parts ....

it showed really handy, when I used it ...

To be usable as part of a CGI (for dynamic sites like REBOL.org), 
we'd either need to edit the script to remove* feature* like =include; 
or (better) Makedoc2 could have some refeinements to limit where 
it can read files from.

Without something like that, features like =include are a security 
risk -- they can read anything on the server.

Ah, good point. I could handle this in MDP light_mode

I use =include to build my reference manuals and file lists inside 
other docs. It's quite essential that it works for me.

Robert, as you say, the mentioned people didn't get to develop the 
standard further, I think, Carl should have the information discussed 
here in this group. What do you think is the best way to contact 
Carl on this? With the feedback link on his blog?

I've founfd the most reliable way to contact RT is via the feedback 
form at rebol.com. 

It doesn't work everytime though.

My opinion is, we shold leave make-doc, bloggger and other topics 
for now, to get Carl's attraction where we really need it ;-) RIF, 
plug-ins, RebServices, Rebin,  AGG beta  are waiting in priority 
list :-)

Robert - MDP light_mode -- the version of make-doc-pro we use a REBOL.org 
has its =include code commented out.  It would be good if there were 
just one version,

Yep working all with the same tool increase the easy knowledge.

and it is so nice to have such a cool document formatter which is 
so easy to use, understand, and improve upon.

I've made an initial specifikation of MakeDoc2. It can be found here: 
http://home.tiscali.dk/john.niclasen/nicom-md2-spec.html

The MakeDoc2 document for that specifikation can be found here: http://home.tiscali.dk/john.niclasen/nicom-md2-spec.txt

i agreed with a cool editor like MDP-GUI that"s even cooler

Great spec Geomol (Specifikation -> Specification), that's the best 
doc I've seen on MakeDoc (any version) to date! ;) It got me thinking 
about a few things; firstly, which of the following is valid:

*One
*Two
*Three

or

* One
* Two
* Three


and, do we *really* need to insist upon a blank line between each 
MakeDoc element? Isn't 'newline more than adequate?


Also, it [the standard] should make it clear that the EOF tag "###" 
is *optional* - I don't want to be told that "you need it to make 
your document work".

blank line is required if you manualy wrap your line at 70/80 char 
because your editor does not wrap by himself (Carl's intention, see 
makedoc2.5 header)

Thanks Ashley about the spelling. Changed!


About the bullet points, both ways seem to be valid. In the script, 
Carl use a rule called "text-block" to follow both types of bullets, 
defines and also comments. It's defined to have optional leading 
space (notice the comment):


text-block: [any space paragraph opt newline] ; ignore leading space, 
extra NL !???

a missing ### used to cause problems at the end of a make-doc generated 
document.  Haven't tested this version for that.

The ### can be left out in the end, no problem here.

you will need it for sure if you do/args makedoc2.r at the end of 
the content.

yup

I verifed that old make-doc.r needed the ### to prevent missing the 
last line, but the new one doesn't...so Ashley can be happy now!

Geomol: Would be possible to show the source for each example immediately 
before it? Perhaps you could treat the "source" as code so that it 
would stand out.

Yes Peter, a more complete spec should have that. For now you can 
see the source for the examples at the bottom of http://home.tiscali.dk/john.niclasen/nicom-md2-spec.txt

Thanks

tente$

Sunanda, MDP already can be run in light_mode. Than it justs create 
a HTML output block but nothing more. You than just do whatevery 
you want with it. So there are no two versions. It's just an other 
operations mode.

=include How about an option to disable it? The CGI could insert 
something like =option include-off into the submitted text and than 
MDP will skip =inlcude commands.

While doing MDP for some time now, the details are the hard part. 
Try to use a definition word that has a - in it. Like:

 	manager-report - This is defined as...

Those things make it hard.

I've started work on a more complete document format based on MakeDoc2.

The specification so far can be seen here: http://home.tiscali.dk/john.niclasen/NicomDoc.html


I would like comments on whether this is a way to go and make it 
a new public format, or I just should keep it for myself to solve 
my own documentation needs. The specification is very compact in 
this version, so feel free to ask, if you have any questions.

Robert =include disable. That would be good.

The same issue may in future affect other "dangerous" commands.  
Maybe have  a generic option to run make-doc-pro in a "sandbox". 
In the sandbox, it'd ignore =include and other dangerous commands.

anyone noticed a bug in table headers in makedoc2? there appears 
to be a newline before the text in the second column of a table, 
which makes it double height and the text is shifted down in the 
header

Yes, I see that too, when using Mozilla, but not with Opera. It's 
because a <b> (bold) is not finished with </b> in the second header 
cell. A bug in the script, it seems.

Should send that to www.rebol.com/feedback.html

Sunanda, that was my idea. The list of dangerous directive can be 
easly extended than.

Have any of you looked close at the MakeDoc2 formatter? It's a 2-pass 
parsing, first converting the text to rebol blocks, and then parsing 
the block(s) producing HTML code. Of course it's smart, because if 
you wanna make a parser producing e.g. PDF code, you only have to 
make a new second level parser. And there's also the problem with 
Table Of Content, which can only be completed after the first pass. 
My first approach with my NicomDoc format was to make a 1-pass parser, 
and build the TOC along the way as separate text, and then only combine 
the TOC and the rest of the document before output. Benefit with 
1-pass parsing would be speed, but downside is, that you need a new 
full parser, if you wanna make PDF code. Then again a parser going 
from some rebol block format to e.g. PDF would probably be almost 
same size as going from a text format (NicomDoc or MakeDoc) to PDF. 
hmm What about XML? Making an XML file from some rebol blocks would 
be pretty easy, same the other way. What should I do? Make a 1-pass 
or a 2-pass formatter?

What is the problem to create TOC as a subblock for second phase 
purpose, during first phase pass?

No problem with that. That would probably be the way to do it in 
a 2-pass formatter. It's only a problem in a 1-pass formatter, because 
you have to do some work anyway after first pass to make end final 
output (incl. TOC).

I think, it'll be best for me to make a 2-pass formatter. Not optimal 
speed, but the whole task look much easier this way. And first pass 
should be a separate rebol script, which wouldn't need much change, 
only if standard changes. And then second pass scripts are made for 
each output format.

That seems the way to go, unless you want to make a compiler compiler.

Yet Anoter Compiler Compiler? :-) No way! ;-)

Another**

Just migrate some more hair from the top of your head to your chin. 
You'll be fine ! :-)

Geomol, MDP takes the same approach. 2-pass parser.