From: Toshiro Kuwabara Date: 2000-03-04T02:24:50+09:00 Subject: [ruby-talk:01709] Re: Ruby 1.4 stable manual bug? Hi, In message "[ruby-talk:01708] Re: Ruby 1.4 stable manual bug?" on 00/03/03, Hugh Sasse Staff Elec Eng writes: >> I've written a document of RD format, here. >> >> and this is HTML version. >> > >This looks interesting. I will put comments at the end. Thanks. >> But We, and RD, cannot accept your idea because it is not fit >> with RD's policy and its goal. >> >> We decided to use the syntax like plain text for RD. And we think >> it is wishable for RD to seem as same as plain text. RD format should >> be ordered same as it is desplayed because this rule is simple. > >There is definately something to be said for simplicity. The only other >thing that occurs to me is that "plain text" is slightly different for you >and for me :-) -- what do you think about a language directive in RD, >which pod also doesn't have, so one can set the RD reader to Japanese, >English, Esperanto or whatever? It would then simply pick out the >appropriate parts, and display those as plain text. Sorry, I might confuse you by my breif, too breif, explanation possiblly. RD's target, i.e. user, is a man such like: * He is a Ruby Programmer. He love Ruby, he also love programing. * He doesn't like writting documents. Ofcourse, he understand how his users need documents. But, he love programing so much that , he think , he have no time to write document. * He knows HTML. He also knows LaTeX system. At least, he can write HTML formated document by his hands. But he don't like HTML. He think HTML is too complicated for him to write documents of his Ruby script. RD's goal is "to make him write documents". So RD must be attractive for him, a lazy Ruby hacker.:-) Why he don't like HTML? Why he think HTML doesn't fit for writting document of his Ruby script? I think that because: * He is enough lazy, so he want not to write such like "..." or something. When he write document, he want to write document itself, not to write something like HTML tag. He want to concentrate to his document itself. * HTML can easily split document and bury it into its tag syntax, I think. While he own his script, add new future to it and fix bugs of it, his document is still alive. He must fix his document again and again. So, HTML doesn't fit with documentation of his script. RD have to help him. So, RD's directive is: :easy to read, easy to write * He must read his document which he wrote 3 month ago, when he up-to-date it. He don't need to read so detail, but he must grasp it and find out where he must change. He read RD itself, not HTML formatted document which rdtool generates. So, "easy to read" is a great point for "easy to write". * It is why we select "plain text like" format for RD. I think, we (and "he") are familiar with plain text, so we grasp easily structures of documents in "plain text like" format. * I think, the appearance of plain text format represents structure of document. (NOTE: this "appearance" doesn't mean "decoration". ) If you write a block indented, such like: class Foo def bar ... end end it will mean "this block is a cited text block or program code". And if you write lines with mark like "*", such like: * A list * ... it will mean "a list, unordered list". We use such notation again and again in our real life, in books, in lecture notebooks and in our daily memos. So, we can understand easily structure of document in plain-text. :easy to learn, keep it simple He wants not to study so much about mark-up language. Ofcourse, LaTeX is good system, but it is too complicated for his usage. LaTeX is something like a programing language. He doesn't want such system. He want "to write document"! So we will keep RD simple. He doesn't want more. He doesn't want fully-automated documentation system. He doesn't want publishing-level printing system. He only wants simple but easy-to-write document format. OK, now return to your suggestion. "Order" is very big point for document structure. If you read the last chapter of a book first, and read first chapter last, you will be confused, maybe. When he fix 3-month-ago document, he will read RD and will be confused, because that RD is written with defferent order from HTML file which rdtool generates from that RD. Especially plain-text-like format is sensitive to order, so your suggestion is not fit with RD, I think. Different man hopes different thing. Each writes document with different style from other. Natural language is much more diffcult than programing language, so each learns his own style of writting for natural language. I understand how different they (we) think what is "wishable". But we can't stuff everything into RD. So, I want each users to write his own script which help him to write RD in your style, instead of fully-featured RD. >> If you want to write RD document like your idea, you can write easily >> a script to convert your style of document into canonical RD. > >I could use the <<< include feature for some of this. Yes. >Having looked at the document, there are a few things I am not clear >about. > Headline: What is the intended difference in meaning between "=" and > "+"? Is it always to be treated as a font size difference? Are > "=" "==" and "===" be regarded as structure like HTML's

> and

, and is it forbidden to render these as different sizes? Yes simply section size difference. "=" is bigger, "+" is smaller. HTML equivalent is: = H1 == H2 === H3 ==== H4 + H5 ++ H6 We don't decide "decoration". So it is free to render it with any size, any font face and any color. > Inlines: Examples of how these might be rendered would be helpful. > I suggest you show them embedded in a Textblock. Oh, I have > just looked at the rd form of the document, and this is clear. Oh, thank you for idea. Now we decide we can use Inline at term of DescList. So, I must fix Inline section of this document. I fix that point at the same time. > Given that the indentation is used for structure, is it intended that > a Textblock at the Baseline level of indent should never have its lines > folded when displayed, or is folding permitted? OK. When it desplayed, RD doesn't restrict such "decoration" anyhow. We decide only that RD's "appearance" represents structure of document. We don't decide about output of RD formatter. But HTML have its own rule, LaTeX also have its own rule, so output of RD formatter must be equivalent of original RD in symantics. > You have the sentence: "RD is one of them, but RD will be a standard > one." I am not sure what you mean by this. Is it that several > document standards can be supported in one file, or will there be > dialects of RD for different situations? Well, this means ... ruby, Ruby interpreter, regards embeded document with very simple way. it simply ignore text between "=begin" and "=end". So, if you want, you can embed other format document, for exsample HTML, in your Ruby script. ... So, "RD is one of them". OK? Suggestions and Questions are always welcome. :-) --- Tosh Toshiro Kuwabara