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

Comments about make-doc-pro?

 [1/19] from: robert:muench:robertmuench at: 8-Aug-2001 11:46


Hi, I hope that some of you had a look at the make-doc-pro script and played around with it a bit. Any comments? Robert

 [2/19] from: lmecir:mbox:vol:cz at: 8-Aug-2001 19:23


> Hi, I hope that some of you had a look at the make-doc-pro script and
played
> around with it a bit. Any comments? Robert
Hi, I like the idea and I am using the make-doc. The simplicity is appealing. But the "dialect" used to specify the document is a little bit "irrebolar" IMO. I would like to have it a little bit more "rebolar" as follows: instead of saying: ===Objective I'd prefer to say: [section] Objective Instead of saying: ---Primary Rule I'd prefer [subsection] Primary Rule Instead of saying *This is a bullet point. *This is another bullet point. I'd prefer [bullet] This is a bullet point. [bullet] This is another bullet point. Instead of saying: #This is the first numbered line. #This is the second numbered line. I'd prefer: [no-start] [no] This is the first numbered line. [no] This is the second numbered line. To include a result of a computation I would like to say: The number PI is [emit pi]. What do you think?

 [3/19] from: agem:crosswinds at: 8-Aug-2001 19:59


RE: [REBOL] Re: Comments about make-doc-pro? Well, the nice thing with make-doc is, it is well readable without any html/whatever-features too. for example the zine's are very readable. this [section] - idea is too agressiv transformation-oriented for me. i like make-doc because "source" works without "compilation" too, which is not the case with html for example. -Volker [lmecir--mbox--vol--cz] wrote:

 [4/19] from: dness:home at: 8-Aug-2001 14:05


Ladislav Mecir wrote:
> > Hi, I hope that some of you had a look at the make-doc-pro script and > played
<<quoted lines omitted: 12>>
> I'd prefer > [subsection] Primary Rule
...
> What do you think? >
I've played around with make-doc (not yet with make-doc-pro, which I should be getting to later today) and I'd _disagree_ fairly strongly with these suggestions. It seems to me that they not only generally require _more_ typing, but also are more prone to misspelling, and thus extra error/correction cycles, during document preparation. Of course, I guess I wouldn't ultimately object to just about anything that could be done/undone with a simple set of perl substitutions, so I don't feel strongly about it, but I do prefer the current way of marking up simple text.

 [5/19] from: dness:home at: 8-Aug-2001 22:34


Robert M. Muench wrote:
> Hi, I hope that some of you had a look at the make-doc-pro script and played > around with it a bit. Any comments? Robert >
I have several. Please read them in light of the fact that I know a fair amount about computing stuff in general, but not very much about REBOL in particular. I like the topic and the implementation. However, there are some things which are either mis-understanding on my part (and thus might point to more documentation) or things I think you might conider changing. Reading the code is fine, for documentation, but it doesn't give sufficient overview to actually make the process useful. If you are not intending to supply further information, I'd make it more extensive. Also, I find it somewhat disconcerting that running your test text creates a live display that starts with `Heading 2' as though something had been forgotten. I'd make the test both more productive and more descriptive. And while I understand using DE for German, I wonder if EN might not be more reasonable than US, although I suppose this could be some REBOL `standard' that I don't know enough to understand yet. I don't get the role of `display' that automatically pops up in the browser, and whatever happens to %index.html. It also strikes me as a _very bad_ idea to destroy my index.html without so much as a by-your-leave, why would I expect your code to do that? In most circumstances I want to be able to do something with the HTML that results from the translation, so I would much prefer that this be written into a file than that it appear `live'. I assume you are probably familiar with `similar' attempts to deal with this problem. One of the better ones, IMO, is Todd Coram's `AFT' (Almost Free Text, which he did with some help from Ward Cunningham of Wiki and Extreme Programming fame). It is at http://www.maplefish.com/todd/aft.html and I would suggest you look carefully at it if you haven't alread done so. He implements many of the facilities you have implemented, as well as some that are on your `future' list. I am writing a paper comparing some of this class of facility for some clients. When I have finished it, I will seek their permission to `publish' it, and will put it on my web site if that is forthcoming. I think you have taken something that was useful, and made it even better. I look forward to further developments...

 [6/19] from: jean:holzammer:faedv-n:bayern at: 9-Aug-2001 8:25


>Hi, I hope that some of you had a look at the make-doc-pro script
and played
>around with it a bit. Any comments? Robert
You aimed to a improved (but as compatible as possible) version of the original makedoc. You added some nice features. Here my suggestions: 1. It's nice to be able to select a language: I would suggest sth. like this to specify it: =language any-string Then you 'do a file called %path-to-makedoc-pro/locale/any-string.r , that defines the localized strings example: %path-to-makedoc-pro/locale/US.r: contents: "Contents" %path-to-makedoc-pro/locale/DE.r: contents: "Inhalt" %path-to-makedoc-pro/locale/EN.r: contents: "Contents" So you wouldn't need to have support for different languages hardcoded into the the compiler. 2. 'browse function exspects a string containing a valid URL. So instead of: filename: %testout.html browse to-string filename you should do sth. like this: filename: %testout.html fullpath: join dirize what-dir %testout.html browse rejoin [file://localhost/ to-local-file fullpath] As browse passes the string given as command line argument to the browser without modification/conversion, it gets an invalid URL ! This might work with _your_ browser, but not necessarily with other browsers. 3. I don't think it's a good idea to use CSS for intendation. If a browser doesn't support this (or the user has disabled that feature) there will not be any intendation at all. 4. You should add an option to disable generating a contents section (have a look at make-spec.r), but without disabling generation of a <title> tag. If contents section is not generated, the first section of the text may not begin with h2 but with h1 instead ! 5. You should put font definitions into an external file (as makespec does), and use no fonts tags as internal default. 6. A function that allows inserting images into the floating text itself would be nice. Just some ideas,... Jean

 [7/19] from: robert:muench:robertmuench at: 9-Aug-2001 14:30


> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 5>>
> fair amount about computing stuff in general, but not very much about REBOL in > particular.
Hi, I have no problem with critic and/or suggestions. I know I'm way off from holding the holy grahl for doing things right...
> Reading the code is fine, for documentation, but it doesn't give > sufficient overview to actually make the process useful.
What process are you referring too?
> If you are not intending to supply further information, I'd make it more
extensive. Sorry, I don't understand what you mean here...
> Also, I find it somewhat disconcerting that running your test text > creates a live display that starts with `Heading 2' as though something had
been
> forgotten. I'd make the test both more productive and more descriptive.
Agreed. This really wasn't meant as test or demo, it was just the source I used to test it... so no really educating intention.
> And while I understand using DE for German, I wonder if EN might not > be more reasonable than US, although I suppose this could be some REBOL
`standard'
> that I don't know enough to understand yet.
Agreed, too. I'm going to change it.
> I don't get the role of `display' that automatically pops up in the browser, > and whatever happens to %index.html. It also strikes me as a _very > bad_ idea to destroy my index.html without so much as a by-your-leave, why
would I
> expect your code to do that?
Allready changed. The HTML file will now use the filename of the source file, and for other files (using =file) the given filename.
> In most circumstances I want to be able to do something with the HTML > that results from the translation, so I would much prefer that this be written > into a file than that it appear `live'.
?? The output is written into a file ?? The generated HTML code is very dense and doesn't provide a nice outline. How about adding a pretty-print feature?
> I assume you are probably familiar with `similar' attempts to deal > with this problem. One
<<quoted lines omitted: 4>>
> carefully at it if you haven't alread done so. He implements many of > the facilities you have implemented, as well as some that are on your `future'
list. Yes, there is even the eText project from Andrew. We have discussed a lot about all these things. But I wanted to keep the make-doc spirit and be compatible to make-doc files, so that make-doc-pro might even adapted by Rebol Technologies. Thanks for the comments. Robert

 [8/19] from: robert:muench:robertmuench at: 9-Aug-2001 14:30


> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 7>>
> So you wouldn't need to have support for different languages > hardcoded into the the compiler.
Hi, I like the idea but I even like the one-file-approach to simplify distribution. Howabout a section of different languages within the source-code? Like the style-sheet stuff?
> 2. 'browse function exspects a string containing a valid URL.
Ok, I'm going to change that.
> 3. I don't think it's a good idea to use CSS for intendation. If a > browser doesn't support this (or the user has disabled that feature) there > will not be any intendation at all.
Well, that was the idea. Than you don't have indention at all, no problem. But I think using CSS is the way to go these days.
> 4. You should add an option to disable generating a contents section > (have a look at make-spec.r), but without disabling generation of a <title> > tag.
Ok, goood idea.
> 5. You should put font definitions into an external file (as > makespec does), and use no fonts tags as internal default.
I haven't thought about this one yet. I would like to use CSS here too. What do others think about the external file approach? How about one external INI file, where all these things are stored in? So only two files are needed: make-doc-pro.r and make-doc-pro.ini
> 6. A function that allows inserting images into the floating text > itself would be nice.
Yes, this is on my to-do-list too. The same applies to URLs etc. Thanks for the ideas :-)) Robert

 [9/19] from: dness:home at: 9-Aug-2001 11:15


Robert M. Muench wrote:
> > Reading the code is fine, for documentation, but it doesn't give > > sufficient overview to actually make the process useful. > > What process are you referring too?
I was (in a muddled fashion) referring to `the process' of getting a document prepared. What I didn't get from reading the code was sort of an overview of the process as in (1) run make-doc-pro; (2) It offers current directory file list and you select file; (3) it runs and outputs to ... Something like that.
> > If you are not intending to supply further information, I'd make it more > extensive. > > Sorry, I don't understand what you mean here...
What I was trying to say was _if_ your _only_ documentation was reading the code, then I'd make the comments in the code more extensive. If you are planning a `separate document' then I'll await that.
> > In most circumstances I want to be able to do something with the HTML > > that results from the translation, so I would much prefer that this be written > > into a file than that it appear `live'. > > ?? The output is written into a file ?? The generated HTML code is very dense > and doesn't provide a nice outline. How about adding a pretty-print feature?
I'll have to look again at the =file command, I may not understand its function, and it may be confusing my world-view. ...
> Yes, there is even the eText project from Andrew. We have discussed a lot about > all these things. But I wanted to keep the make-doc spirit and be compatible to > make-doc files, so that make-doc-pro might even adapted by Rebol Technologies.
I'd say you succeeded.

 [10/19] from: cybarite:sympatico:ca at: 10-Aug-2001 11:15


Robert, I had some ideas on make-doc a few months ago and sent them off to rebol tech. You can review them if you like at http://www.cybarite.com/public/make-doc-enhancements.html [Carl--rebol--com] responded with some comments that the highlighting tag would be a good idea but just have one and give it parameters that would enable different looks. P.S. I liked the recommendation to use more readable tags like [section] Comments rather than ===Comments but because there is now a legacy of "===", I think it will be hard to change. But that does not mean that "[section]" can not also be supported via a change to one line. From the version that I have Carl was already supporting an alternative to "===" which was "-1-". So the code was: ["===" | "-1-"] TEXT-LINE (EMIT-SECTION 1) | and it could become ["===" | "-1-" | "[section]" ] TEXT-LINE (EMIT-SECTION 1) |

 [11/19] from: dness:home at: 11-Aug-2001 15:05


Mike Myers wrote:
> You can review them if you like at > > http://www.cybarite.com/public/make-doc-enhancements.html >
This is nice, but it would appear, flawed. At least when I view it the document header indicates a section 9, and yet the document itself dies ungraciously early in section 8. Not that it matters much, but the document also has a very poor internal HTML structure, as least if you look at it from the viewpoint of the various validators that you can pass such documents through. If this is to be a `public' facility it would seem to be a good idea to at least attempt to conform to widely-shared standards.

 [12/19] from: cybarite:sympatico:ca at: 11-Aug-2001 19:29


At 03:05 PM 8/11/01 -0400, [DNess--Home--Com] wrote:
>Mike Myers wrote: > >
<<quoted lines omitted: 12>>
>would seem to be a good idea to at least attempt to conform to widely-shared >standards.
Thanks for the comments David. I looked at doctor html (http://www2.imagiware.com/RxHTML/) and am very impressed with the analysis it gives. So I'll have a go at cleaning up my html exceptions it throws. I did post them so that Robert Muench might consider any of the approaches in his make-doc-pro script. Making them readable might help sway him to implement some of them. but I have been thinking that using Carl's easyvid.r dialect is a better communication vehicle for an audience that has acces to View.

 [13/19] from: dness:home at: 11-Aug-2001 22:38


Mike Myers wrote:
> Thanks for the comments David. I looked at doctor html > (http://www2.imagiware.com/RxHTML/) > and am very impressed with the analysis it gives. > > So I'll have a go at cleaning up my html exceptions it throws. >
You're welcome. My guess is that you'll find it productive
> I did post them so that Robert Muench might consider any of the approaches > in his make-doc-pro script. Making them readable might help sway > him to implement some of them. > > but I have been thinking that using Carl's easyvid.r dialect is a better > communication > vehicle for an audience that has acces to View. >
I'll look at that. Thanks for the pointer.

 [14/19] from: robert:muench:robertmuench at: 13-Aug-2001 16:30


> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 4>>
> but I have been thinking that using Carl's easyvid.r dialect is a better > communication vehicle for an audience that has acces to View.
Hi, how about an easyvid like emitter for make-doc-pro input files? Robert

 [15/19] from: robert:muench:robertmuench at: 13-Aug-2001 16:30


> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 4>>
> I had some ideas on make-doc a few months ago and sent them off to rebol tech. > You can review them if you like at
Hi, thanks a lot, I downloaded them and I'm going to have a look at your ideas.
> P.S. I liked the recommendation to use more readable tags like > > [section] Comments > > rather than ===Comments > ...
I really don't know if it makes sense to support several different versions for the same tags. I saw that === and -1- can be used synonym. I don't know what's better. IMO the -1- approach is more natural for people not used to write with non WYSIWYG systems.

 [16/19] from: cybarite:sympatico:ca at: 13-Aug-2001 20:50


At 04:30 PM 8/13/01 +0200, Robert M wrote:
> > -----Original Message----- > > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 5>>
> > communication vehicle for an audience that has acces to View. >Hi, how about an easyvid like emitter for make-doc-pro input files? Robert
Yes! I think that is consistent with why Carl moved from make-spec.r to make-doc.r .... the ability to publish to different formats from a single source. Today I did something along these lines by adding the ability to my version of easy-vid.r to emit an arrow image. In the VID Usage tutorial I had copied in some of Carl's presentation bullets and arrows and I think they present very well. I was thinking that this will look good so that the easy-vid.r can be used for presentations. ..... but the single source approach of make-doc to emit easy-vid makes more sense.

 [17/19] from: dness:home at: 13-Aug-2001 21:34


Continuing comments on easy-vid / make-doc-pro ... Has anyone made a version of easy-vid that interfaces `code' segments to languages other than REBOL? Let me put the question in context. Those of us who do some of our work in J make use of J's `tutorial' capability to write instructive material about the J language, and problem solving in J. J's tutorials are ok, but IMO, REBOL's clearly look leagues better. and are much more managable and effective. I would like to be able to write J tutorials that would allow me to execute J fragments in the same way that easy-vid allows me to execute REBOL code fragments. I understand, of course, that it would be `my job' to figure out how to get REBOL to `talk to J" in an appropriate fashion. Given that J's own IDE `talks to J' in a straightforward way, this should, I think be doable. Is this a silly thing to attempt? Or can some one give me a pointer to get me started down the appropriate path... I note, in passing, that REBOL might also make a wonderful IDE for `K', which currently pretty much uses EMacs console mode on the input side and IE (HTML) on the output side, but I go into `overload' when I start to think about that prospect.

 [18/19] from: coussement:c:js:mil:be at: 14-Aug-2001 13:21


Robert: I've just been confronted with this problem: the portability of HTML documents when used with images. It's a known pitfall that you have to move your html doc + its images, as those are not embedded :-( make-doc-pro could solve this by providing a section where embedded images (tag =image) are defined under their binary form... It could even pre-process the document skeleton and embed the image itself into the section. Just a thought ;-) I don't have the time now for implementing it myself. cheers, chr==

 [19/19] from: robert:muench:robertmuench at: 14-Aug-2001 16:07


> -----Original Message----- > From: [rebol-bounce--rebol--com] [mailto:[rebol-bounce--rebol--com]]On Behalf Of
<<quoted lines omitted: 4>>
> I've just been confronted with this problem: the portability of HTML > documents when used with images.
Hi, yes one of the big problems with HTML pages IMO. Microsoft has a very neat solution for this. You can save a complete page inclduing all graphics as .mht file. This seems to be a MIME encoded multi-part thing. I would like to have a mode where I can emit a self-contained .mht file. I hadn't time to look at the structure yet. Does anyone has infos about this kind of file format? Robert

Notes
  • Quoted lines have been omitted from some messages.
    View the message alone to see the lines that have been omitted