r3wp [groups: 83 posts: 189283]

# World: r3wp

## [Make-doc] moving forward

 newer last Geomol9-Jan-2005[1] Work on Open Document Format is done here: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office It may be a good idea to keep an eye on that project.  Pekr9-Jan-2005[2] I am not sure if I am wrong or not, but Open Office 2.0 should be a bit different - both faster, more MS Office compatible, but should also support open document format. If so, it is good for open office ...  Geomol10-Jan-2005[3x4] Sections in documents  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 ] ]  Pekr10-Jan-2005[7] 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 ....)  Geomol10-Jan-2005[8x2] 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 , and going back is done with . So it's no big problem for me to write code indented as makedoc require.  Pekr10-Jan-2005[10x3] 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 ...  Henrik10-Jan-2005[13] is makedoc2 a branch of makedocpro or makedoc?  Pekr10-Jan-2005[14] imo of make-doc, as it was developed by Carl at RT .... while md-pro was developed from version 1 of make-doc, iirc ...  Henrik10-Jan-2005[15] looking forward to proper tables support... which seems not to work yet in make-doc-pro  eFishAnt10-Jan-2005[16x2] 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.  Geomol10-Jan-2005[18] 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?  eFishAnt10-Jan-2005[19] I have one...I think it was makespec.txt and on the world wide Reb...(through View Desktop) methinks.  Geomol10-Jan-2005[20] Ok, I found "make-spec.txt". I'll use that as an example. Thanks!  eFishAnt10-Jan-2005[21x3] 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  Henrik10-Jan-2005[24] is it beyond the scope of makedoc2 to be able to create indexes from keywords?  Geomol10-Jan-2005[25x14] 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: This text is bold.This is bold and italic.This is just italic.  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.   bla bla bla bla bla bla  That last thing is a table fully within another table. The first table is ended at the end, not where the first tag is.  Back to the bold'n'italic example. It should be done this way: This text is bold.This is bold and italic.This is just italic.  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.  Pekr10-Jan-2005[39x3] 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?  Geomol10-Jan-2005[42] 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.  eFishAnt10-Jan-2005[43] not the whole thing, just the parser ... but I have stuck it together various ways in Developer/IOS for experimentation and testing.  Pekr10-Jan-2005[44] 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 ....  eFishAnt10-Jan-2005[45x2] 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..  Geomol10-Jan-2005[47] Do you use tags like \note, /note, \table and /table?  Pekr10-Jan-2005[48] 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!  Geomol10-Jan-2005[49] If you do use those tags, I guess, this will be a problem: \note A note \table some text /note more text /table  eFishAnt10-Jan-2005[50] 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.  newer last