 | | legOS docs - what do people want?
|
|
hello, I am a logOS documentation volunteer, and I am curious as to what type of documentation the user community would like to see. What level of detail is required? What standard format should be used? How about usage examples of the various (...) (26 years ago, 19-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
Dwayne Jacques Fontenot wrote in message ... (...) well I was planning on lurking here for a while and try some of my "newsgroup osmotic learning", but since you asked :) I would be looking for: "getting the very interested (and capable) beginner (...) (26 years ago, 19-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) I would like to see a high level overview, api documentation similar to that created by doxygen, and then examples of usage for each call. (...) HTML works well. The MS Win32 API documentation is a good example for an API documentation layout. (...) (26 years ago, 19-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) I think it would be coolest (and most helpful) if the docs were in a super- portable format, either PDF or, heck, just darn plain old HTML. HTML would be great because it could easily go on the CD-ROM (if there is one) for Jonathan's O'Reilly (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) I'd vote for PDF over HTML. For one thing, a PDF document will be considerably smaller in size than an equivalent HTML document. HTML also has the less-than desirable characteristic (in my opinion) of "fragmenting" a hypertext document across (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) really good (...) I wholeheartedly agree! I've downloaded and installed the egcs binaries but could never get LegOS to compile because of my path environment as well as numerous other issues. I also concur that PDF would be a more desirable (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
Mark Tarrabain wrote in message <36CE02AF.8C000243@l....bc.ca>... (...) Yes this is a brilliant Idea! I agree. LINC (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
In this vein, what is the distribution of OS's people are using (or attempting to use) with legOS? Personally I am a linux user and feel comfortable explaining that. As for Windows 95/98/NT it might be better if someone who uses legOS on those (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | PDF (was Re: legOS docs - what do people want?)
|
|
More than a few people have emailed me already telling me that PDF is not the way to go because it will limit who can contribute to it (thank you to those people, by the way, for keeping such comments to email rather than cluttering the newsgroup (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) I have linux and Win NT, but my linux machine is not always available, so I would like to be able to build legOS on my NT machine. (...) Dave Madden once told me that he was working on some scripts and docs to show how to install egcs and (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) Unfortunately, I don't have any facilities to download the entire contents of a web site. So I would rquire somebody to tar and gzip the html files in the documentation subtree at the legos site and send it to me for conversion. (Now before I (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) I _can_ read PDF files, but I would discourage making it the form that docs are released in. I find reading PDFs to be a painful experience. My display is only 1024x768, and at that resolution, reading the output of any page description (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) Ahh, but this specialized newsgroup -is- for cluttering up :) with comments of that nature -- as long as things remain on-topic to legOS and still helpful to Markus and comrades. (...) It costs money? Bummer. So only the viewer is free then? (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
It definitely needs to be portable! (...) please no PDF, it is portable but a pain to read on a screen and I've always thought that it was easier to read api documentation on your computer screen since this is were you work (...) one) Also if you (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
Mark Tarrabain a écrit dans le message <36CE02AF.8C000243@l....bc.ca>... (...) super- (...) considerably (...) less-than not when compressed (...) document (...) slightly you can always have one html file (...) Reader is (...) name I agree with the (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) Well I think you got a point I missed there, PDF is not free (compared to html) although the viewer is, adobe acrobat definitely is not. (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) a web site. So (...) subtree at the (...) This is exactly the reason I would prefer a PDF version of the document. You can get the entire document in one shot. For printing, I like PDF much better than TeX. It has free viewers for Macs, (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) True, but there are freely available PDF generators (htmldoc coming to mind most readily). Adobe Distiller is the one supplied with the commercial version of Adobe Acrobat. (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) PDP-11? FreeBSD, Solaris, XENIX, other flavors of Unix? NT, presumably. Win 3.1? DOS? Apple ]['s? Just some off-the-top of my head paltforms, that i somehow doubt are _all_ supported... Jasper (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) (smile) I never should have written "either ... or" above. =:*) Certainly, since there is demand for both PDF and HTML forms of the docs, and since the HTML form will just happen no matter what, and MarkT has offered to create the PDF form (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
I like the pdf format. I have no trouble reading it either on my laptop (800X600) or on this machine (1280X1024). I use the "fit width" option, and have never seen the text be "too small" in either case. It is becoming commonplace in the industry, I (...) (26 years ago, 22-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
Thanks, Todd, I think you have (hopefully) circumvented the "I hate pdf" and "HTML sucks" threads that were cranking up in response to this... -- SeeYa ! ---...--- Jim ---...--- Hello... Is this thing on ? Todd Lehman wrote in message ... (...) (26 years ago, 22-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
Well as long as there is an html version I don't care. I still think pdf is a pain to read because it doesn't scroll well. (26 years ago, 22-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) Well what about ONE html file. Nobody ever said you had to fragment html files. Or whatabout a group but zipped or tar.gzed (26 years ago, 22-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: legOS docs - what do people want?
|
|
(...) online (...) modem-dialup (...) US$20- (...) hourly-metered (...) 6 (...) pretty (...) The problem isn't the ISP but the phone charge. And the speed of the transatlantic connection at peak hour (like when you are home to dial). Also you still (...) (26 years ago, 22-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
Hello. The API documentation tool I use can generate HTML, LaTeX and manpages. Unless Dimiti expands its capabilities to also generate PDF - or somebody points me to a better tool and volunteers to convert the sources that exist already - HTML (...) (26 years ago, 23-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
It's Doxygen. (URL) doc++ is also a viable alternative, but I've used doxygen before in Qt-based projects, where it is clearly superior. (26 years ago, 23-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
Well, I've waited and waited, but nobody has volunteered to send me the existing docs to convert to PDF. I'm afraid I don't have the facilities myself to download the entire documentation tree at the LegOS site. I thought that freely offering my (...) (26 years ago, 24-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) Hmm... Well, I think it was only earlier today that Markus officially gave his blessing on conversions to other formats (not that we thought he wouldn't, but it seems fair to wait and see for sure). So going by what Markus wrote here: (URL) (...) (26 years ago, 24-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) Thank you Todd. I'll work on it tonight and email the pdf back to you sometime tomorrow. (...) (26 years ago, 24-Feb-99, to lugnet.robotics.rcx.legos)
|
| |
| | Re: PDF (was Re: legOS docs - what do people want?)
|
|
(...) I'm not sure I'd know what to do with it. I'd be happy to see how it looks on my system, but I think Markus is the destination you want, since he'll be the one hosting it (I assume). --Todd (26 years ago, 24-Feb-99, to lugnet.robotics.rcx.legos)
|
