AltME groups: search

Of course, I prefer REBOL data, with makedoc being my preferred markup 
format. I don't know if Carl's WIP wiki is worth asking about, or 
another wiki engine or site would not lock us in too much. Some of 
us did some work on a wikimedia interface for R3 docs, which didn't 
get far. And I have a wikidot site we can play with if people want.

About the tooling, a wiki approach + makedoc format makes sense to 
me.

Makedoc format allows the addition of REBOL code at the end. The 
proper way to generate the doc files is to CD to the folder, then 
run REBOL on %red-system-quick-test.txt

Can you add a link to the makedoc files on each html page?

There is no makedoc files, I'm using the Blogger platform (Google). 
Unfortunately, a bad choice, it is an awful blogging platform, the 
only part that doesn't suck is the Google Analytics integration.

I'm not sure the Makedoc version I'm using supports PDF export though...it 
might need an upgrade to MD3.

I have a rather tortuous path using makedoc => asciidoc => pdf/epub

Yes, Gabriele has a PDF generator. Don't remember if it supports 
MakeDoc format

My own website is done with Cheyenne and the HTML dialect and is 
very easy for me to maintain: Makedoc files are rendered on the fly 
to each webpage. I can SSH to the server and edit files as I please 
and there is nearly zero HTML involved.


Granted, there is no blog or comments section, but is another example 
of how a small toolchain (one Cheyenne executable and a few script 
files) can be used to build a good website.

For Red header, I've made it case sensitive on purpose as, unlike 
Rebol which is a very uncommon name, Red is very common, the risk 
of a false header detection is much higher (for scripts embedded 
in HTML, makedoc document, etc...). So the case-sensitivity would 
lower the number of false positives. An added benefit is that it 
forces users to write Red name correctly, so not RED or red.

I've got a question about using MakeDoc/MakeDoc Pro vs Markdown/MultiMarkdown. 
Are there significant advantages with MakeDoc that outweigh going 
with Markdown which seems to be the defacto standard for lightweight 
markup? I guess when MakeDoc first came out it was pretty unique, 
but if you were to need this kind of tool today wouldn't it make 
sense to use something with wider adoption?

Makedoc for Rebol3 from Chris http://chat.stackoverflow.com/transcript/message/10001554#10001554

It would be really enough to have MDP accept MD's style of headings.
 - are you referring to MakeDoc or MarkDown? :-)

As much as I love makedoc, and as many docs as I have in that format, 
a more widely adopted standard that is close in syntax and features 
seems like the best option as a standard.

Arnold, yes, there are many competent document systems out there, 
but there hasn't been anyone that could be so easily plugged in and 
used as MakeDoc and MakeDocPro. I just want to move beyond their 
current limitations, so Saphirion can deliver professional, high-quality 
manuals to the customers.

Thanks for posting that link Ted!


I, too, want an all-REBOL toolchain and format. However, I view MD/MDP 
as a very basic format for plain communication and HTML generation. 
It is not a "structured" document format.  And while extensible is 
good, we can probably come up with a spec that outlines all that 
might need to be handled, to help guide a baseline design. e.g., 
while it's XML, DocBook was well thought out IIRC.


I admit that one of my problems with makedoc, historically, is consistent 
behavior and support for images and links. 

Don't forget Gab's QML either.

@Gregg, asciidoc uses a header *because* it's a document formatting 
tool.  There's a variety of styles supported .. and it's a pain to 
try and remember but I guess it gets easier with use.  The point 
for me is that it provides entry to docbook and then multiple other 
formats whereas makedoc/pro are stuck in a single page style html 
which is really past it for any serious documentation.

so to get back to pitfall vs. stylistic - i notice that carl's scripts 
(makedoc, blog) tend not to copy 'global' literals

The structure of MD since v2 is a separation of scanner and emitter. 
'scan-doc will break text into a block of [style content] pairs. 
'gen-doc will take that block and turn it into something, most commonly 
HTML.


The features of your doc - using your ==+, ==#, etc. are in the spec 
of the parser. Loosely explained, the parser's rule 'resets' when 
it encounters a newline.  It defines a few paragraph types that copies 
chunks of text (including 'paragraph that consumes text AND single 
newlines).  The rest of the rule determines the paragraph style and 
expected paragraph type:

  "===" text-line (emit sect1 text)

Could just as easily be:

  "==+" paragraph (emit my-bold-paragraph para)



The way a document is presented is all in the emitter. Seems this 
is where you seem to be yearning for most control. My first motivation 
using MakeDoc was stripping it of any styles - I just wanted a minimum 
of HTML markup that could be embedded and properly moulded by CSS. 
In my script above, I iterate through the [style content] list and 
use 'switch to determine how to handle each, this should be sufficient 
for documents without any complexity. It's really then just a case 
of modifying the HTML that is emitted.



Example of script used in RSP (exposes [escape-html scan-doc gen-doc]):


  <link rel="stylesheet" href="http://ross-gill.com/styles/anywhere.css">
  <% do http://reb4.me/r/xhtml%>

  <pre><code><%= mold doc: scan-doc some-input-text %></code></pre>
  <%= gen-doc doc %>

How it looks depends on the stylesheet you use.

I think a wiki like Wikibooks could be a good start, but I would 
like to use makedoc format. I know that the R3 wiki has been adapted 
to accept makedoc format as input, how could we do the same for Wikibooks? 
Is it possible to export all wikibook content to a parse-able format? 
I don't want to be trapped in a given tool, I want to be free to 
retarget docs to whatever format/tool we find appropriate in the 
future.


If wikibooks is not the best tool for the job, we might want to install 
a copy of R3 wiki on another server.


The only issue I have with wikis is that we need someone in charge 
there, reviewing every single change and filtering them when needed. 
Without someone fulfilling that role, it will quickly become a big 
mess.

Someone also wrote a makedoc GUI, didn't they? Are there tools like 
that for managing a doc base? I also agree with some earlier comments 
about some commercial sites having very good docs. How do they do 
it?

Gabriele wrote a MakeDoc GUI a long time ago.

We might have another good alternative option to the wiki (maybe 
easier and more flexible): use a github repo for all the    documentation 
pages in makedoc format, and have external export batch script to 
export them in HTML, PDF or whatever format.

AdrianS: Github Pages uses Markdown format, they have no support 
for makedoc.

So the Red docs are not makedoc(2) specific. You only want to be 
sure that they are in a format that can be handled using scripts 
like makedoc123 and generate all kinds of documenttypes, like webpages, 
pdf, (epub?) etc. If I understand correct.

Makedoc would be the source format for the docs, the users would 
consume it in one of the exported formats available.

I've got a question about using MakeDoc/MakeDoc Pro vs Markdown/MultiMarkdown. 
Are there significant advantages with MakeDoc that outweigh going 
with Markdown which seems to be the defacto standard for lightweight 
markup? I guess when MakeDoc first came out it was pretty unique, 
but if you were to need this kind of tool today wouldn't it make 
sense to use something with wider adoption?

Hmm, I think you are in fact mixing up implementation with syntax. 
Are you saying that MakeDoc markup is not something that can/should 
be able to be processed by non Rebol tools?

Gabriele's MD3 is fairly awesome, imo. Very easy to build MakeDoc 
'dialects'.

Has MDP ever been really associated with RT? I always thought it 
ways Robert's creation. Whereas MakeDoc and MakeDoc2 where Carl's 
stuff.

we should probably try to make it clear for newcomers when we mean 
MakeDoc(2) vs Markdown, which some people might think MD refers to

Adrian, I'm not certain, but I believe the settled extension (and 
I suppose shorthand) for MakeDoc is .rmd (Rebol MakeDoc).

Which makedoc version should I use to compile those mdp files? I 
used makedoc2.r but the output html file is not correct completely?

makedoc-pro?

no, not yet. It's definitely on the list though. Is that fairly straightforward 
with MakeDoc by any chance?

makedoc just gives you one very long page .. so that should be okay

<<How about a man command that looks up the manual pages on the net, 
and dumps them to the console?>>

It wouldn't be that hard to adapt the existing code for other purposes 
too.

Like, it'd be good  if someone extended it to emit MakeDoc codes. 
Those files could then go straight up on the web -- instant searchable 
ocumentation.

I get the impression that Carl would be happy for people to volunteer 
to extend the project.

It's a glitch between REBOL.org's escaping of codes and makedoc's 
escping of codes.

Someone has to do it to prevent XSS attacks via contributed documentation, 
but not both of uss.

Part of the problem  is that almost all Dialect==>HTML converters 
assume they are there to produce browser-ready HTML. In tne real 
world that isn't always true: they are a step in a pipeline.
I'll sort it out soon. Thanks for reporting the problem.

Yeah, we are still fixing a bunch of these type of errors with our 
MakeDoc and QML to HTML converter.  It is very funny to make self 
referencing system.

@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.

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?

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.

your examples do work pretty good on the new makedoc...just tried 
them in Developer IOS.

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".

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?

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've updated my NicomDoc specifikation: http://home.tiscali.dk/john.niclasen/NicomDoc.html

(NicomDoc is a working title, and I just specify this format, because 
I need to make a lot of specifikation and documentation myself in 
the future, and I don't think, MakeDoc suits my needs. I've also 
looked at make-doc-pro, and it's close to what I need. I hope, we 
can specify one open format, that will suit us all.)

I've also updated my comparison of NicomDoc vs. MakeDoc2: http://home.tiscali.dk/john.niclasen/NicomDoc-vs-MakeDoc2.html

Yes, tools like MakeDoc are about focusing on content, not style. 
It's great if we have a *way* to do more complex things (extension, 
manual tag insertion, etc.), but they shouldn't be a priority.

But it's not what I need. MDP-GUI is a help for those who don't know 
MakeDoc rules.

I just want an editor that help me to insert the most bothering tags 
(like <b></b>) arround the text I want.

Typing tags is not very confortable on French Keyboard : < and > 
are on the same key and the last require Shift. / require Shift too. 
So typing tags all the time is very annoying.

mark tags in a different way. maybe {tag} or [tag]. then exchange 
"{" with "<". then makedoc.

yeah .. it would be good to be able to choose which variant of makedoc 
to use.

Ashley thank you very mutch for the tips ;) I will work on special 
adaptation to MDP format requirement on the redering process. Option 
tu use makedoc 2  sure but in this case your cute MD2IDE will be 
deprecated and I  doesn't want that... MDP and MD2 have similar form 
but diferent kind of rendering processs. I don't want to make a monster 
application ... I want to make a quick usefull little GUI to write 
aesyly MDP formated programs with lot of automation like save on 
quit, recent file list, etc...

Okay, I downloaded makedoc2 from rebol.org the other day and I still 
haven't figured out how to create links. In makedoc all you did was 
"url=http://www.rebol.com"REBOL" " but that just shows up as text 
in makedoc2. Could you help me out?

wikiDoc = makeDoc with dokuwiki syntax; 
http://www.rowery.olsztyn.pl/wspolpraca/rebol/wikiDoc/

Do one knows why "=url" is not part of makedoc 2.6 (nor 2.5) ??

Micha: no MakeDoc (Pro) tylko dla konverzji z MD formatu do HTML 
...

Robert : For the structure, you can look at my 'Easy-Doc prototype:
http://rebol.dev.fr/view.php?sid=141
It works with 3 sets of modules: readers, parsers and writers. 

'readers have to supply a text string to parsers (ie. MS-Word files 
are scanned for text),

'parsers build a block in intermediate format (there is a makedoc 
parser,)

and 'writers output the result either in file or on screen (VID / 
html / pdf / rtf / swf).

I was thinking that another good feature to add for makedoc is a 
javascript popup link

Mike, that Treemenu looks like the same one a site that I now frequent 
uses at http://www.peshitta.org/Which is good but I need something 
that might be a building block to a full blown viewer at some point 
in the future.  For example there are other bible viewers such as 
e-sword but I want something that can support additional book names 
and might make the makedoc extended to support a format as that and 
maybe make a conversion tool that will take some of the popular bible 
formats and output them to text and rthen back in through a tool 
and output the makedoc format so that the output is still compatible 
with makedoc.

I have been inspired by the make-doc line.  Robert's rendition is 
fantastic.  Love the whole site in one file thing.  Keeping the CSS 
out of the rendered html is good, using classes.


MDP-Browser sounds really cool.   a makedoc/spec browser for makedoc 
formatted scripts.


I have been playing with a document format that I call nulldoc, which 
is mostly a set of generaly rules about how plain text documents 
have been formatted traditionally, or how plain text copied from 
a web browser can look, and I started developing a set of broad regular 
expressions to markup plaintext.


based more on what I wanted than what I actually had, the rules I 
came up with go something like:

two blank lines begin a new nulldoc document (segment)
spaces/numbers/letters/symbols represent lists.

tabs/spaces at the beginning of the line denotes code/hierarchy. 
 

tabs that are trapped by non-space on both sides means tabular data.


I differentiate between code and hierarchy indentation by short-circuiting 
code switch with #:


	code section

#	numbered section


I wrote a web page that reads the KJV aloud using an MS Agent character. 
  Used a control from MS for a menu   I had it voice-activated, but 
that was a drag so I used "web navigator control"  stupid name for 
a menu.  I think it's still up at http://members.cox.net/rovingcowboy/kjv/
 probably won't speak unless you have sapi 4 voice installed, though.

What part of the code of makedoc lets me change the individual lines 
being written to 'out?

Paul

If you want to stay with some minor changes to makedoc2, then just 
copy what is provided for NOTE.
Add your verse to the data

\verse author verse
content text
/verse


This is assuming author and verse will be text strings (no spaces). 
Unlike NOTE you need to parse the text after \verse to get the two 
parts so that you can plug them into the output where you like.

Note uses text-line:  [any space copy text thru newline]

which puts everything on the line from the identifier tag \NOTE into 
the variable 'text


One direct way to get the values author & verse from the line is 
by reparsing what text gives you 
that is you let the \verse processing work the same as \NOTE


  | "note" text-line (emit note-in text)   ; this is an existing line

  | "verse" text-line (emit verse-in text) ; this will be added to 
  support verse
		
		note-in     [emit-note doc/2]    ; this is an existing line

  verse-in   [emit-verse doc/2]    ; this will be added to support 
  verse

emit-note then has an emit-verse parallel

emit-verse: func [text] [

 words: parse text none   ; Because text-line was in the rule for 
 verse it contains author and verse

 emit [<div class=verse-box><p class=author> words/1 </p> "&nbsp; 
 " <p class=verse> words/2 </p>]
]


and because you should handle the /verse tag similar to /NOTE which 
should close the html table and the div.

In the above that author and verse are defined as classes so you 
can leverage stylesheet independently of makedoc.

Paul, I don't see how makedoc can do that because one of the goals 
was to having simple tagging where the input source is very readable. 
For these the line prefix (===, ---, ... etc) is that simple tagging. 
To be able to differentiate any value you would have to tag it independently 
and a general template can't know what you want to do.  

If you change the base makedoc to use an external stylesheet instead 
of the embedded styles in the template, you are a long way to getting 
what you want. Combine that with the few special tags you need and 
you can accomplish a lot within the design goals noted.

A quick one for the makedoc pros: How do you tell makedoc2 to not 
make a table of contents. I think it has something to do with no-toc 
but...

The REBOL MakeDoc Page

 - Updated 27-Jan-2005 ... /  "The MakeDoc Standardization Project" 
 - Updated 26-Jan-2005 ... Is there any activity left regarding those 
 project ?

I don't find URL support as described in http://www.rebol.net/docs/makedoc/md1.html#section-5.5
 in the released makeDoc version accessible at http://www.rebol.org/cgi-bin/cgiwrap/rebol/view-script.r?script=makedoc2.r
   Rambo 488 raised for this.

Is there any easy way to get blank columns in makedoc tables?

Am I correct that tables in MakeDoc are only vertical?!!?

Is there way to make a table in MakeDoc that has the first column 
all dark, then each column to the right is white?

Is it me or is there not a hidden option to make 2 column output 
in makedoc 2? I seem to remember one.

Mike, I was thinking like this: http://www.rebol.net/docs/makedoc.html

; Options still need work!!!
 <---- found this in the source code for makedoc 2 on rebol.org


Does this mean that reusing makedoc in the same run-time session 
really is broken? If I turn off table of contents for one doc, it 
will not be on for the next for example.

options are now cleared properly before a makedoc document is scanned.

I think there is great potential to unifying all the tools that are 
forming now: pdf-maker, AGG, SVG input and makedoc2. Allow these 
things to talk to eachother! imagine making a drawing in AGG or import 
an SVG into a DRAW and then use the very same block with layout-pdf. 
Future versions of makedoc could print pdfs as well as HTML through 
pdf-maker. by letting these tools use eachother, the combination 
could be a very fast and powerful document creation system.

so you can create books or magazines with just makedoc or qml. :)

the pdf maker is not a markup language :) it's a (rather low level) 
dialect. you generally want to hook up higher level mls to it (like 
makedoc and qml)

wetan is an emitter for makedoc. so the ml is still makedoc basically 
:)

yet it's something for higher level dialects to do imho. i.e. makedoc 
would do that.

LOL, I meant as in HTML, MakeDoc, etc.

there's also to say, that the layout-pdf dialect is still meant to 
be rather low level. a human would write in QML or makedoc or some 
high level dialect, not layout-pdf; thus the defaults for image would 
be useless (even if a human was to write it, they'd only cover some 
10-20% of the cases, since not all images have the same dpi, and 
99% of the time you don't want the image at the bottom left corner 
of the page).

Is there any way to go from pdf to makedoc format?

Though many scripts in the Library are just one script file plus 
one documentation file. That doesn't need to be a package:
http://www.rebol.org/cgi-bin/cgiwrap/rebol/cpt-recent-docs.r

The documentation can be in Makedoc or Makedoc2 format (plus some 
other formats too, like Nicomdoc)

I think trying to arrive to the level to inkscape in our own SVG 
DRAW MAKER software will take more than one year to redone it with 
REBOL... So to avoid loss of time we can yet work on the engine for 
rebgui feeting to InkScape SVG format then we can start working to 
our own SVG DRAW MAKER made in full REBOL... One thing that afraid 
me a little is the flexibility of the SVG format as it can be very 
different how to support any SVG file comming from any EDITOR ? For 
me SVG appears to me to be close to what we done with MakeDoc format. 
Today we have many MD like format all very good but to make a Viewer 
in rebol that support them all it wil be very very difficult.

makedoc to latex?

I have tried "Overflow: auto" (I just had a look to makedoc anywhere 
result to see how it handles that),
but fall on the I.E. inconsistency.

wikiDoc - makeDoc with syntax similar to dokuWiki
http://www.rowery.olsztyn.pl/wspolpraca/rebol/wikiDoc/
http://wiki.splitbrain.org/wiki:syntax

I'am very badd in dialects so I can't be of any use all my dialectal 
creation approche was learn thru makedoc it's good but not enought 
to imagine and write a vid like application

Henrik --- One question: how good is the SEO on your site? Little 
point putting cookbook entries where they are hard for the world 
to find.


One idea: why not write a wiki-formatting to HTML function (you'll 
need it anyway) and donate it to the Library ?.....

.... REBOL.org can then accept cookbook entries and other articles 
in wiki format --- we already accept all other major formats: MakeDoc, 
NicomDoc, eText etc.  And we do have good SEO.

100% done with makedoc. :-)

makedoc knows columnar design? Or this one is done via css?

G, Is that true? "100% done with makedoc. :-)"

James: yes, the site is completely build with makedoc. a version 
with some modifications, sure, but still makedoc. (Chris' CMS with 
some changes by me.)

To become part of the RP a library will need to adhere to these requirements:
- BSD license
- docs in HTML/makedoc
- code accepted by RP lead

Uniserve is very nice, I have been using it to prototype/test before 
I upload to actual server.  It broke my heart it was gpl.  BSD is 
very good choice.  Free software should not be restricted, and GPL 
has too many of those.    makedoc/spec is the killer app,  and in 
that intensional programming vein is coursing all the best documentation, 
and REBOL  does a fine job of documenting itself because it is so 
semantic by nature.  To understand how to use a moderately complex 
system like a full-featured web server, it is going to be important 
to capture the thinking of those who wrote the code.  REBOL parsing 
allows all information pertaining to the code to be right there with 
the code,  and a function of  DO -ing anything.  the standard documentation 
scheme should follow how REBOL [] headers work, and simply have the 
makedoc embedded within the scripts.

Gabriele is writing a PDF emitter for MakeDoc and QML.

Oh, agreed....................my thought was simply how many dialects 
we are all working with, and how this number will grow until there 
is need for a new approach.


For example, XML is a dialect of sorts, for transmitting discrete 
data.  PS for rendering information in 2D.  HTML for rendering information 
in such a way that those that are challenged can us verbal readers, 
or physically challenged can ID links and important parts.  MakeDoc 
for converting  few symbols to complex rendering instructions that 
can be represented by HTML.

that is probably true. however I may change the architecture a bit 
since the parser is limited to two levels and is not recursive. the 
pages are generated from a limited list. all I really wanted to do 
was to make it easy to combine blogger.r, makedoc documents, dir 
listings and customized html output in a pipeline. it does most of 
that now, but the parser is only about 80% elegant. :-)

Should take regular MakeDoc formatted text.

(forgot how odd makedoc was).

Any reason not to?


If only I could figure out how to insert a carraige return after 
the image on teh front page in the reduced MakeDoc command set....