World: r3wp

A document format should build on the hierarchical datamodel. That 
can lead to problems, when sections are defined with "tags" like 
\in and /in (to make something indent) and \note and /note (to make 
a note).

This is valid:
\in

\note A note

example

/note

/in

This is invalid:
\in

\note A note

example

/in

/note

A better way to make sections in documents is to use something like 
a block. Example:

\in [

\note A note [

example

]

]

I think that make-doc needs some design work. What I liked about 
md-pro was, that it allowed to include source code. The need for 
source code to be intended is terrible. Dunno how you, but I tend 
to write my code from the beginning of line (column 1) and intending 
it by hand in the case of longer script is time consuming .... (and 
I don't want to use another script to preformat script for the purpose 
of its inclusion ....)

When doing it this way, it's not possible to finish \in before \note 
is finished. My example here may not be optimal, but it show the 
problem.

Feel free to comment on this!

@Pekr: I use the vi editor (now mostly vim) to write code, and it 
allow me to set auto-indent, so when I start something indented, 
it'll stay indented, when I go to next line. Further indenting is 
done by inserting a <tab>, and going back is done with <backspace>. 
So it's no big problem for me to write code indented as makedoc require.

well, I am not sure I want to start to rewrite my code because of 
make-doc ;-)

besides that - ability to "include" source would be better, as the 
code could easily exist in separate file, so changes to the code 
will be reflected in make-doc document, when regenerating ...

for now I can live with that ... that was just some food for thought 
from my side ...

is makedoc2 a branch of makedocpro or makedoc?

imo of make-doc, as it was developed by Carl at RT .... while md-pro 
was developed from version 1 of make-doc, iirc ...

looking forward to proper tables support... which seems not to work 
yet in make-doc-pro

thanks for the ideas guys...I didn't bring the checklist back over 
here yet...but read your ideas.

I understand what you are saying about indentation of emitted code.

In the original MakeDoc dokumentation (http://www.rebol.net/docs/makedoc/md1.html), 
a "makedoc.txt" file is mentioned as an example. I can't find this 
file. Is it still available somewhere?

I have one...I think it was makespec.txt and on the world wide Reb...(through 
View Desktop) methinks.

Ok, I found "make-spec.txt". I'll use that as an example. Thanks!

I am always interested in input, so please let me know what you like, 
hate, etc.

wrt your comment on "hierarchical datamode

...there is a new way of grouping done in make-doc2

is it beyond the scope of makedoc2 to be able to create indexes from 
keywords?

I think, it's crucial to stick with the hierarchical datamodel, when 
making document formats.

Let's take bold and italic as an example:

This text is bold.

This is bold and italic.

This is just italic.

If we use the HTML tags and NOT sticking with the hierarchical datamodel, 
those examples could be done as:

<b>This text is bold.<i>This is bold and italic.</b>This is just 
italic.</i>

So not using the hierarchical model, we can end bold in the middle 
of doing italic text. That is confusing, because then we should be 
able to do the same with tables.

<table> bla bla bla <table> bla bla </table> bla </table>

That last thing is a table fully within another table. The first 
table is ended at the end, not where the first </table> tag is.

Back to the bold'n'italic example. It should be done this way:

<b>This text is bold.<i>This is bold and italic.</i></b><i>This is 
just italic.</i>

So if we stick with the hierarchical datamodel, it's a bad idea to 
use start- and end-tags, because it's then possible to do it wrong, 
and not sticking with the standard.

A better way is:

\b [This text is bold. \i [This is bold and italic.]] \i [This is 
just italic.]


When using a block, it's not possible to end something in the wrong 
place.

If I tried and wrote:

\b [This text is bold. \i [This is bold and italic.] This is just 
italic.]


The result would be, that the first and last text is bold, the middle 
is bold and italic. So "This is just italic." would actually be bold.

I maybe wouldn't get the result, that I wanted, so I had to change 
my text, but my text would be fully understood by the parser. This 
having start- and end-tags is a big problem with HTML, because people 
produce incorrect HTML code all the time, because it's possible. 
If HTML used some kind of a block structure in stead, a lot of incorrect 
code wouldn't exist, and it would be easier to make a browser.

RTF (Rich Text Format) seem to use the hierarchical datamodel too, 
but RTF solve the problem in an interesting way. My above example 
would in RTF be something like:


{\i0\b This text is bold. {\i This is bold and italic. {\b0 This 
is  just italic.}}}


\i0 means setting italic off, \i set it on. \b0 set bold off, \b 
set it on. A problem here seems to be, that you have to tell the 
condition of bold and italic for all text, and I don't like that.

what about alread mentioned open office format? Well, I expect it 
being rather complicated XML, but who knows ...

I mean - open document format ...

Steve - is make-doc2 downloadable anywhere?

One of the goals with the MakeDoc format is, that it's possible to 
easily read with a normal text window, and some people may want to 
edit it with a normal text editor and write the formatting chars 
themselves. XML is not suited for that. XML also has the same start- 
and end-tag problem (that I mentioned above) as HTML.

not the whole thing, just the parser ... but I have stuck it together 
various ways in Developer/IOS for experimentation and testing.

have you already looked into Robert's MDP? Back at the time of IOS 
Developers I used it extensively, including #include ... so I did 
script, which made doc out of many different sources ....

make-doc sorta chops up that problem, Geomol, in my way of thinking. 
 It gets para from newlines but sub formatting is possible...not 
sure if that answers your inquiries well enough

I have done some pretty strange experiments internally with it...will 
demo before too long, but having a blast.  I use several different 
customized make-docs for various things around here..

Do you use tags like \note, /note, \table and /table?

that is not a good thing, to have several incompatible variants imo 
... that is why there is make-doc project, which should produce make-doc3, 
open enough, allowing still the same level of easy of use, why otoh 
providing nicely formatted output ... I like what Chris did at Ross-gill.com, 
you can see output using two different .css files. Well, delete them 
and it will still work, even without .css!

If you do use those tags, I guess, this will be a problem:

\note A note

\table

some text

/note

more text

/table

ah, you misunderstood, Pekr.  make-doc2 is standard, but there will 
be thousands of products that developers create which utilize the 
standard core of it.

I like the things Chris and Robert have done to extend make-doc...and 
enabling different outputs from the same content is a very good thing. 
 no disagreement from me. (and make-doc2 is open source and very 
small, not so hard to work with.

(I used what you mentioned in the DevCon web pages, BTW)

Geomo: I think that is a problem anyway...to have a note criss-crossed 
with a table?  What would you want the outcome to look like?