r3wp [groups: 83 posts: 189283]
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search
 

World: r3wp

[Make-doc] moving forward

shadwolf
11-Jan-2005
[180]
i agreed with a cool editor like MDP-GUI that"s even cooler
Ashley
11-Jan-2005
[181]
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".
DideC
11-Jan-2005
[182]
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)
Geomol
11-Jan-2005
[183]
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 !???
eFishAnt
11-Jan-2005
[184]
a missing ### used to cause problems at the end of a make-doc generated 
document.  Haven't tested this version for that.
Geomol
11-Jan-2005
[185]
The ### can be left out in the end, no problem here.
eFishAnt
11-Jan-2005
[186]
you will need it for sure if you do/args makedoc2.r at the end of 
the content.
Geomol
11-Jan-2005
[187]
yup
eFishAnt
11-Jan-2005
[188]
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!
PeterWood
11-Jan-2005
[189]
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.
Geomol
11-Jan-2005
[190]
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
PeterWood
12-Jan-2005
[191]
Thanks
shadwolf
12-Jan-2005
[192]
tente$
Robert
12-Jan-2005
[193x3]
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.
Geomol
12-Jan-2005
[196]
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.
Sunanda
12-Jan-2005
[197]
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.
Henrik
12-Jan-2005
[198]
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
Geomol
12-Jan-2005
[199]
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.
[unknown: 5]
13-Jan-2005
[200]
Should send that to www.rebol.com/feedback.html
Robert
13-Jan-2005
[201]
Sunanda, that was my idea. The list of dangerous directive can be 
easly extended than.
Geomol
16-Jan-2005
[202]
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?
Pekr
16-Jan-2005
[203]
What is the problem to create TOC as a subblock for second phase 
purpose, during first phase pass?
Geomol
16-Jan-2005
[204x2]
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.
Anton
16-Jan-2005
[206]
That seems the way to go, unless you want to make a compiler compiler.
Geomol
16-Jan-2005
[207x2]
Yet Anoter Compiler Compiler? :-) No way! ;-)
Another**
Anton
16-Jan-2005
[209]
Just migrate some more hair from the top of your head to your chin. 
You'll be fine ! :-)
Robert
16-Jan-2005
[210x2]
Geomol, MDP takes the same approach. 2-pass parser.
More precise: 2-pass script. First parse, second generate.
Geomol
16-Jan-2005
[212]
I've updated the NicomDoc specification: http://home.tiscali.dk/john.niclasen/NicomDoc.html

And I've started implementation of the first pass of the formatter.
Robert
16-Jan-2005
[213]
Why again a new one?
Geomol
16-Jan-2005
[214x3]
Carl made MakeDoc and started a project some months ago to define 
MakeDoc2, but it seems, the group fail to make progress, so Carl 
wrote something about it lately and published some scripts. As I 
see it, MakeDoc has some bad ideas around commands like \note /note 
\table /table and so. Those things should be strictly based on the 
hierarchical datamodel, else users of the format WILL make errors, 
as we see it with HTML, XML and the like. And MakeDoc2 also miss 
bold, italic and the like, which is done as HTML tags. I need to 
make a lot of specifikation and documentation for my projects, so 
I desided to make my own format, that suit my needs. I don't know 
yet, what I should do with it yet, but I'm going to do it. :-)
I hope, it'll be part of a general format, everybody will use, some 
day - maybe merge with MakeDoc2!? It's not my decision.
(ops! I made some bad sentence construction there. Sorry about that. 
I hope, you understand me.)
Robert
16-Jan-2005
[217]
You know make-doc-pro?
eFishAnt
16-Jan-2005
[218x2]
make-doc2 is a current interrim which has his improved starting point, 
so we don't have to start with make-doc 1 generator
as I said earlier, there are thousands of products which the core 
of make-doc from RT will generate.  It is pretty easy code to extend, 
once you get the hang of it.  Make-doc2 gives us a much better springboard 
to do things right, with a better user experience out of the box.
Robert
16-Jan-2005
[220]
Maybe I wasn't that clear. MDP uses the same approach as makedoc2. 
Parser and output-generator are seperated. I really don't see any 
advantage in a next fork. IMO it makes more sense to change what 
we have. Feel free to do so with MDP and submit your changes back 
to me. I will integrate them.
Chris
16-Jan-2005
[221x2]
It's not impossible to write a Make-Doc(-Pro) parser that is compatible 
with Make-Doc(-Pro) outputters too, but then you lose the ability 
to interchange documents.
It is still my greatest request though, that =anyword and \anyword 
/anyword be a part of the make-doc standard.  Thereby building MD 
dialects based on usage context.
Robert
16-Jan-2005
[223]
Chris, I agree. Maybe not the most elegant way but it works quite 
good and we have a lot of docs now. So why change it.
eFishAnt
16-Jan-2005
[224x3]
I was reacting to Geomol, just trying to clarify, not to your statement, 
Robert.  From RT perspective, Carl said he doesn't want to rewrite 
the thousands of documents already written.  I think for someone 
to get RT buy-in for new versions that RT would like, that is a major 
water test.
I think, for the way Geomol is thinking, that his best approach would 
be to enforce his heirarchical structure on the writer, he might 
need to make his rigor as a pre-make-doc dialect that would feed 
to make-doc dialect.  Not hard to do, or he can bypass altogether. 
 Lots of room for experimentation, since the source is there.  Tremendous 
advances can be made by good experiments.
for =anyword, \anyword /anyword...this type of work is made easier 
by the current release, so it is clearer now how to shoe-horn it 
in.
Chris
16-Jan-2005
[227]
I think unless you have one already set up (eg. =url, \table), then 
=anyword would become [anyword "Content"] and \anyword would be [anyword-in 
"Content"]
eFishAnt
16-Jan-2005
[228x2]
Geomol might find an absolutely huge market for his product, as he 
designs something new the way he sees fit.  That is not something 
we can predict for him.  Markets are fickle.
that seems very clever, Chris.