Menu
▾
▴
gobo-eiffel-develop
|
From: Eric B. <er...@go...> - 2001-05-31 21:06:42
|
Does anyone in this list have some experience using DocBook to write documentation? I suggested using DocBook to write the documentation of Gobo and I would like to know your opinion about that. PS: If you don't know what DocBook is, it's an XML format to write technical documentations. It is used to write Linux's documentation, and as a consequence there are already many tools supporting it. From a DocBook file, we can then use one of these tools to generate an HTML file, or pdf, Postscipt, etc. Here are some URLs: http://www.DocBook.org/ http://www.oasis-open.org/docbook/ http://www.nwalsh.com/docbook/index.html http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html http://www.amazon.co.uk/exec/obidos/ASIN/1565925807/ -- Eric Bezault mailto:er...@go... http://www.gobosoft.com |
|
From: Roger B. <ro...@ei...> - 2001-06-01 21:10:22
|
Eric wrote: > Does anyone in this list have some experience using > DocBook to write documentation? I suggested using > DocBook to write the documentation of Gobo and I > would like to know your opinion about that. We really struggled to find a good documentation tool to use for my current project. For the first few months, we used LaTeX. This was a real backwards step for me. I have no problem with using command-line tools, but this one just was too inconsistent. An example of the problems: Eiffel identifiers use lots of underscores, and in some places (e.g. headers) you must escape these with a backslash, but in other places you do not need to (or must not) escape them. Therefore, search-and-replace becomes a real pain because you need to use regular expressions even to find occurrences of identifiers. But from a single source we could get beautiful PostScript output and passable HTML output. Then, Adobe released a beta version of FrameMaker for Linux. I'd not used FrameMaker before, but I had used Ventura Publisher which is a similar long-document-oriented desktop publishing application. (Sadly, Ventura has been badly bugridden ever since Corel bought it from Xerox). FrameMaker worked really well. It did exactly what we needed for technical documentation. Unfortunately, after a year the beta expired and Adobe decided that there wasn't a commercial reason to release FrameMaker for Linux. So we moved to DocBook. It's a very pleasant markup to write in. The DTD is clean, readable, easy-to-learn and well-suited to software documentation. But we never produced HTML that looked really good. It was OK, but there were too many quirks in the spacing, and a small number of other irritating quirks such as character set incompatibilities. It just didn't look good enough that I could be proud of it. Don't get me wrong ... it's quite usable, but the HTML tools don't produce output that looks as good as Eric's. I wanted to be proud of the documentation that we were producing, and DocBook just wasn't good enough. Since then we've played with StarOffice. You can generate beautiful PostScript output, but again the HTML is not perfect. Maybe I'm being too fussy, but I think there really is a problem getting good PostScript and good HTML from the same source document. It seems there must be some compromises along the way. Now I know that good documentation can be produced for software, because I have seen it. For a long time, I have been meaning to ask Eric what tools he used to achieve his clean, consistent appearance. I was disappointed when, a few days ago, Eric posted that he did them "by hand". Oh well. I think an HTML-only solution should be quite acceptable. Those who want to download the whole document for offline browsing can download a tarball of all the pages. And composing HTML is something that is easily available to most people (Netscape Composer or FrontPage). If PostScript is really needed, it can be produced by just "printing to file" from a web browser, and there are open-source tools that can concatenate PostScript files to join all the stuff together into a "book". Finally, PDF should never be a problem: the Linux tool "ps2pdf" turns PostScript into very nice PDF. If you want to look beyond this, the Ruby documentation tools use a clean, simple wiki-like markup. I don't know if they do PS/PDF, but the HTML output looks good. I've not tried these tools myself though. Regards, Roger -- Roger Browne - ro...@ei... - Everything Eiffel 19 Eden Park Lancaster LA1 4SJ UK - Phone +44 1524 32428 |
|
From: Charles H. <cha...@ea...> - 2001-06-01 21:48:47
|
Roger Browne wrote: > Eric wrote: > > >>Does anyone in this list have some experience using >>DocBook to write documentation? I suggested using >>DocBook to write the documentation of Gobo and I >>would like to know your opinion about that. >... > I think an HTML-only solution should be quite acceptable. Those who want > to download the whole document for offline browsing can download a > tarball of all the pages. And composing HTML is something that is easily > available to most people (Netscape Composer or FrontPage). > > If PostScript is really needed, it can be produced by just "printing to > file" from a web browser, and there are open-source tools that can > concatenate PostScript files to join all the stuff together into a > "book". > > ... > Regards, > Roger > The trouble with using HTML tools, is that text documentation needs features that HTML does quite poorly. Indexes and Paginated Tables of Contents come to mind as good examples. If you go with HTML, you are OH BUT DEFINITELY making print documentation a second class choice. The importance of proper pagination in print documents is hard to overstress. A Table of Contents is important, but for reference work a good index is even more important. P.S.: This is also something that a great many HTML sites do quite poorly. OTOH, some do it rather well. It depends largely (though not entirely) on whether or not they include a good search engine for perusing the documents. And just downloading an HTML file won't automatically supply one with this capacity. If docbook enables good text document generation, then please consider how much post-processing would be needed to polish the HTML (and whether or not a script could do it). -- Charles Hixson Copy software legally, the GNU way! Use GNU software, and legally make and share copies of software. See http://www.gnu.org http://www.redhat.com http://www.linux-mandrake.com http://www.calderasystems.com/ http://www.linuxapps.com/ |
|
From: Andreas L. <no...@sb...> - 2001-06-01 23:12:52
|
On 01 Jun 2001 22:09:16 +0100, Roger Browne wrote: > So we moved to DocBook. It's a very pleasant markup to write in. The DTD > is clean, readable, easy-to-learn and well-suited to software > documentation. But we never produced HTML that looked really good. It was > OK, but there were too many quirks in the spacing, and a small number of > other irritating quirks such as character set incompatibilities. It just > didn't look good enough that I could be proud of it. Don't get me wrong > ... it's quite usable, but the HTML tools don't produce output that looks > as good as Eric's. I wanted to be proud of the documentation that we were > producing, and DocBook just wasn't good enough. I never wrote anything with DocBook. I just looked up the specs recently. IMO it should not be a big deal to write our own DocBook->HTML tool that generates HTML the way we want it. This will be even easier if we only settle for a subset of DocBook (we surely don't need some of it's features - they seem to have special tags for special domains alot) regards, Andreas |
|
From: Berend de B. <be...@po...> - 2001-06-02 08:37:45
|
Roger Browne <ro...@ei...> writes:
> For the first few months, we used LaTeX. This was a real backwards step
> for me. I have no problem with using command-line tools, but this one
> just was too inconsistent. An example of the problems: Eiffel identifiers
> use lots of underscores, and in some places (e.g. headers) you must
> escape these with a backslash, but in other places you do not need to (or
> must not) escape them. Therefore, search-and-replace becomes a real pain
> because you need to use regular expressions even to find occurrences of
> identifiers. But from a single source we could get beautiful PostScript
> output and passable HTML output.
And even the underscore problem is easy to fix with just this
definition:
\catcode`\_=12
With DocBook it seems I can still compile the output to pdf using the
tex formatting engine. So I like this choice a lot.
And I think generating HTML should also be possible, either converting
the XML to HTML or else converting to ConTeXt (macro package similar
to latex but more powerful) and converting that to
HTML.
Groetjes,
Berend. (-:
|
|
From: Eric B. <er...@go...> - 2001-06-02 10:43:36
|
Roger Browne wrote: > > So we moved to DocBook. It's a very pleasant markup to write in. The DTD > is clean, readable, easy-to-learn and well-suited to software > documentation. But we never produced HTML that looked really good. It was > OK, but there were too many quirks in the spacing, and a small number of > other irritating quirks such as character set incompatibilities. It just > didn't look good enough that I could be proud of it. Don't get me wrong > ... it's quite usable, but the HTML tools don't produce output that looks > as good as Eric's. I wanted to be proud of the documentation that we were > producing, and DocBook just wasn't good enough. That's something that worried me as well: I never saw on the Web HTML pages generated from DocBook that looked really good. That's why I asked Andreas if it was possible to write a translator DocBook -> HTML using his Eiffel XML library. Or at least with a subset of DocBook. I see no reason indeed why it wouldn't be possible to generate HTML which looks like the current Gobo documentation from an XML file written with the DocBook standard. The advantage of using (a subset of) DocBook if Andreas (or someone else) can write our own customized DocBook -> HTML converter is that we would benefit from the already existing tools (and the ones to come) supporting the DocBook standard, get access to pdf, postscript and other formats for free, and surf the XML wave which is getting bigger and bigger. > Now I know that good documentation can be produced for software, because > I have seen it. For a long time, I have been meaning to ask Eric what > tools he used to achieve his clean, consistent appearance. I was > disappointed when, a few days ago, Eric posted that he did them "by > hand". Oh well. Do you mean for flatshort forms or for the overall documentation in general? One of my problems is that I'm too perfectionist. It can be seen as a quality (the appearance of doc and software looks consistent, assertions are well defined, etc.), but it can be seen as a fault as well: no tool is good enough for my needs and I end up doing a lot of things "by hand". This is the case for example for the flatshort forms which appear in the Gobo documentation. I didn't find a tool yet which does what I want. So I ended up being my own tool ;-) But more seriously one day I will have to write such tool which formats the flatshort forms the way I want, especially because I don't think it is reasonable to ask the new contributors to the Gobo project to do their own doc by hand as well. I guess I'm the only one to be that masochist ;-) As for the doc other than flatshort, I guess that its formatting is consistent as well, but it's not that much of a problem to write it by hand since the most difficult part is writing the doc, not formatting it. And I didn't find a tool which can write the doc for me yet! > I think an HTML-only solution should be quite acceptable. Those who want > to download the whole document for offline browsing can download a > tarball of all the pages. And composing HTML is something that is easily > available to most people (Netscape Composer or FrontPage). So, would you suggest that we keep HTML to write Gobo documentation until Andreas (or someone else) comes up with a customized DocBook to HTML converter which generates nice looking Web pages, and then try to switch progressively to DocBook using this new tool? > If PostScript is really needed, I only got one request so far from a user wanting to print the documentation of Gobo in pdf or postscript format. But the advantage of DocBook (provided that we can generate nice looking HTML) is that we get this for free. -- Eric Bezault mailto:er...@go... http://www.gobosoft.com |
|
From: Frieder M. <fm...@ob...> - 2001-06-02 08:41:51
|
We used it internally at OT .. Alexander <kw...@ah...> knows a lot about it. I personally like another approach: I defined a small subset as DTD which (in my eyes) is more suited for daily work. Translating these XML files into docBook is then trivial. (the same applies for any "short" form .. if its in XML, then you have Docbook already - just apply some small XSL transformations :-) So, there should be no discussion about: Should we XML for documentation. If the answer is "yes", then the final format is only a minor question. -- Frieder Monninger Object Tools GmbH fm...@ob... --- http://www.object-tools.com Nordstr. 5 - D 35619 Braunfels - fon +49 6472 911 030 fax 031 |
|
From: Eric B. <er...@go...> - 2001-06-02 10:43:37
|
Andreas Leitner wrote: > > I never wrote anything with DocBook. I just looked up the specs > recently. IMO it should not be a big deal to write our own DocBook->HTML > tool that generates HTML the way we want it. This will be even easier if > we only settle for a subset of DocBook (we surely don't need some of > it's features - they seem to have special tags for special domains alot) But on the other hand they don't have special tags for Eiffel ;-( If we add these tags for Eiffel, it will not be DocBook anymore and we won't be able to use tools supporting the DocBook format. Is that correct? Or can we hijack some tags and use them to specify Eiffel specific entities? To what extent is the DocBook format flexible (or is it not flexible at all)? -- Eric Bezault mailto:er...@go... http://www.gobosoft.com |
|
From: Andreas L. <no...@sb...> - 2001-06-02 11:18:46
|
On 02 Jun 2001 12:31:45 +0200, Eric Bezault wrote:
> Andreas Leitner wrote:
> >
> > I never wrote anything with DocBook. I just looked up the specs
> > recently. IMO it should not be a big deal to write our own DocBook->HTML
> > tool that generates HTML the way we want it. This will be even easier if
> > we only settle for a subset of DocBook (we surely don't need some of
> > it's features - they seem to have special tags for special domains alot)
>
> But on the other hand they don't have special tags for Eiffel ;-(
> If we add these tags for Eiffel, it will not be DocBook anymore
> and we won't be able to use tools supporting the DocBook format.
> Is that correct? Or can we hijack some tags and use them to specify
> Eiffel specific entities? To what extent is the DocBook format
> flexible (or is it not flexible at all)?
Don't remember the exact tag names, but they have something like:
<listing name="C++">
void main () {...}
</listing>
So we can use that. I believe that the best way would be to start with
DocBook imediatly. Even if we don't get perfect results now, we will
have a smooth upgarde path (once we write our own tools). And even if we
at some point decide that DocBook is to limiting, a tool to convert it
to any other format will be easy to do, because we have all the meta
information and can parse it very very easily.
I am totaly for DocBook. Also I belive that with the current tools you
can supply your own style sheets. Maybe that helps us in the short term
to get better HTML results.
Andreas
|
|
From: Berend de B. <be...@po...> - 2001-06-02 15:05:54
|
Andreas Leitner <no...@sb...> writes:
> Don't remember the exact tag names, but they have something like:
> <listing name="C++">
> void main () {...}
> </listing>
I think pdf doc generation shouldn't be a problem. Take a look at
eposix-manual.pdf to see what's possible. My ConTeXt Eiffel mode
generates OOSC2 Eiffel formatting.
So DocBook to pdf through ConTeXt will just run fine, I'll will make
sure of that. You can get any layout you wish.
Generating HTML like Eric does might be harder, I don't know. Perhaps
it's easy to adapt my Eiffel mode to generate Eric's makeup, I haven't
looked into detail if that is possible.
Straight from DocBook to HTML and getting a decent markup is
hard, I suppose. As there are also jadetex -> latex -> latex2html
possiblities, I think we don't limit ourselves in anyway. But certain
output might take some work, but is never impossible.
Groetjes,
Berend. (-:
|
|
From: Frieder M. <fm...@ob...> - 2001-06-02 19:19:11
|
1. There is a book available at O'Reilley .. 2. As a nice example one can do with PDF - have a look at http://www.renderx.com/Tests/hammer/hammer.fo.html in special, and http://www.renderx.com in general :-) 3. Again: Do it in XML - no other format. What scheme/dtd is used does not matter so much. Unfortunately there is no need to use eiffel for transformations - XSL is something like a functional programming language to transfor XML into nearly everything ... -- Frieder Monninger Object Tools GmbH fm...@ob... --- http://www.object-tools.com Nordstr. 5 - D 35619 Braunfels - fon +49 6472 911 030 fax 031 |
|
From: Berend de B. <be...@po...> - 2001-06-02 08:34:23
|
Eric Bezault <er...@go...> writes: > Does anyone in this list have some experience using > DocBook to write documentation? I suggested using > DocBook to write the documentation of Gobo and I > would like to know your opinion about that. I would rather have everyone use ConTeXt :-) But I'm quite happy with this choice. I can perfectly handle XML with ConTeXt so I can still influence the layout at will. Groetjes, Berend. (-: |
|
From: Eric B. <er...@go...> - 2001-06-02 10:43:36
|
Berend de Boer wrote: > > I would rather have everyone use ConTeXt :-) I don't know ConTeXt, but from its name I guess that it is a TeX based tool/format. I'm not sure that everyone wants to use TeX based formats. The advantage of XML based formats is that it's fun. But don't get me wrong: it's not fun because it's any better than TeX or other formatting languages. It's fun in the sense that more and more people are using it, more and more tools are supporting it, and finally it's fun because it's related to the internet. This is a questionable definition of what fun means, but I guess that it is questionable as well to see people using Java instead of Eiffel ;-) -- Eric Bezault mailto:er...@go... http://www.gobosoft.com |
|
From: Alexander K. <kw...@ah...> - 2001-06-05 09:01:05
|
Eric Bezault wrote: > Does anyone in this list have some experience using > DocBook to write documentation? I suggested using > DocBook to write the documentation of Gobo and I > would like to know your opinion about that. I have some experience with DocBook and some other issues discussed here last few days. Here are my comments: 1. DocBook 1.1. Writing It seems to be the real way to write the documentation. I cannot say that many products support this XML out of the box, but there is enough tools to make the things rolling. Even WYSIWYG can be approached to some extent (I written a CSS that styles the DocBook document under XMetal - XML editor). 1.2. Program code DocBook is mostly developed to write texts rather than code. There are some constructs that allow to write class/feature declarations but not implementations. These constructs are potentialy language-independent, but the real tools support only C, C++, Java and, maybe, few others - not Eiffel. If we talk about Norman Walsh XSLTs it's possible to provide Eiffel rendering and ask him to include it to the distribution. 1.3. Modularity When I started to use XML DocBook (after using SGML version), I tried to minimize elements/attributes I would use. This is possible due to modular structure of the DocBook DTD. However, that did not work. Day after day I included back tables, cross-references, index terms, glossary elements, footnotes, ... - almost everything DocBook gives. The story is a little bit different with attributes. There are many of them that I did not use. So, to simplify writing, a half of them was excluded. DocBook DTD allows to add elements and attributes that are not the standard part of it. It might be possible to add Eiffel-specific markup, but I have no actual experiance with it. 1.4. Colors All output I've seen for DocBook documents is black-white. I do not know whether multicolored schemes can be used for the output. 2. HTML formatting 2.1. Problem with automatically generated HTML The reasons of bad-looking HTML mostly deal with the browser. The same HTML looks very differently under different browsers. Some of them seem to expect hand-written HTML. Reformating HTML to the "expected" form improves the results. Examples of the formating that tricks the browsers are: spaces around some elements, elements not starting from the new line, new line inside the element tag, "unexpected" combination of nested elements. Fortunately, w3c provides a tool (tidy) that modifies HTML to be in the most "expected" form. Other appoaches like SED/AWK can be also used. 2.2. Styles HTML can look much more attractive if it uses CSS. The HTML output for DocBook document can include classes for the elements, so customization via CSS becomes a lot easier. Unfortunately, not all browsers support CSS properly. 3. PDF output Simple markup usually can be converted to PDF without problems and the resulting PDF can look pretty good. When the layout becomes complex, especially when complex tables are used, the PDF is just unacceptable (I tried both free FOP and commercial renderx). Regards, Alexander Kogtenkov Object Tools, Moscow |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X