Re: [Cooker] cooking on documentation
On Fri, 2 Feb 2001, Matt Morrison wrote:
She asked if there was programs that presented man in html and I said
that I thought so. Then she said why isn't it used automatically, is
this some tribal rite you unix fantasist must undergo when you learn new
things.
Speaking of which...
I'm currently starting a project on sourceforge called php-man-gateway
(throw that in front of sourceforge.net to get the homepage). There's really
nothing there at the moment except a minimal PHP script that pipes the
output of 'man [section] command' through 'col -b' to remove nasties and
displays it inside of a pre /pre block. I'm hoping to eventually make a
functional alternative to 'man2html' in PHP, with automatic linking to other
pages, fun colors and font sizes, and all that type of stuff. As it exists
currently, check out http://mattman.dhs.org/man.php for the real thing,
man.phps for the source. Hopefully I can get the sourceforge site somewhat
functional in a few days, and get development going. Any help would be much
appreciated, as this is as much an excercise to teach myself PHP than
anything else.
I'd like to contribute to this project. I'm fairly fluent in PHP, having
just used it to put together a web-based database, and I think this
unification of the assorted documentation is a good idea.
Some of the features I'd like to see (and am willing to code are):
Ability to access man, texinfo, HOWTO, /usr/share/doc/..., rpm -qi
information through the same interface.
Nice presentation (ie not just using pre-formatted text in the way
Konqueror does currently). This will probably require use of the .texi
source for the texinfo docs.
Good cross-linking between the various types of documentation. In
particular, a man page that says "I'm out of date, use the texinfo
documentation instead" should never be displayed. Links from man pages
("See also:") should not go straight to the target man page, but should
go to a general "about this topic" page that then has links to all the
relevant types of documentation on that topic.
A search facility, either using 'apropos' or possibly by letting htdig
index the whole PHP-generated documentation tree.
Some kind of advice on which source of information to look at. If a
particular topic has a man page, an info page, a HOWTO and some
documentation under /usr/share/doc/, then the user should not just be
presented with a blank list, but also with a few guidelines on where to
start (e.g. "for basic instructions on how to use this command" - man
page, "for in-depth details" - /usr/share/doc/... etc.)
The main problem I can foresee is that we will need Apache running on
every machine in order for this to work.
Michael
Re: [Cooker] cooking on documentation
Michael Brown wrote: The main problem I can foresee is that we will need Apache running on every machine in order for this to work. Michael Hi A newcomer to Linux about a year ago would have had Apache running all the time, started by RedHat or whatever. How many seconds does it take to warm up your model, not much. You are painting a nice picture of the future for a newcomer to Mandrake. regards guran
Re: [Cooker] cooking on documentation
Hiya Guran, Guran, I can understand your frustration. I'm one of the developer that contributes to Mandrake (I'm from cyest.org). The thing that UNIX developers (including me, sometimes) *often* overlook: we develop a program that interacts "Human" with "Computer". Sometimes we forget about the human part. For example: "ls","mv","cp","tr","vi","yes" - these are pretty confusing for me in the beginning when I switched to Linux. Designing a user interface that really meets the necessity of 100% user level from every area - beginner to expert, is not easy. If you take a look, for example, my program, gnome-telnet. It was designed to be very very easy with a complete and easy documentation. Still, the users ask me 'funny' questions about what is already clearly documented there. You wouldn't believe it if you were me. At first, I thought it was the user's fault. Then, after thinking for a while, I realized that one of the part is that my design might not have met the level of familiarity required by certain people. Each human has different perceptions of what is called "easy to use", "user friendly". We still need to work a lot on the "Human" with "Computer" interface and interaction in Linux. Linux is considerably user friendly because it's _very_ fast (if you know how to speed up), and it's very stable (no frustrating blue screen, GPL, etc), and the documentation in /usr/share/doc/HOWTO/HTML/en/index.html is pretty much complete (although yes, it *is* still hard for new users to find out how to do this, how to do that). Based on my experience, I need more time to learn programming under Linux than under Windows. The only solution is that we develop a better and friendlier documentation. This will be improved in the future. Many people (including my friends) have given me a very constructive criticism about this. I am committed to bringing Linux to a much friendlier state. There is _always_ a place for improvement :-) I'm still working on Drakupdatetxt, gnome-telnet, SubNetwork explorer (to explore someone's network topology etc). I'm very glad that your post give me a very good insight about how important a documentation is. I'm still 19, however, I hope when I'm a little older (probably 21 or 22), I will be able to develop a program that meets the majority of people's demand in terms of user friendliness. Thanks, Prana http://www.cyest.org Tom wrote: On Friday 02 February 2001 02:08 am, guran wrote: As an old teacher I showed her were the documentation was situated. OK, now you're qualified (??) She asked me why not all documentation was to be reached more nicely through the icon titled documentation. It is, and it's also on the menu under 'Documentation' I could not find a good answer. maybe ya need to go back to sckool ?? one thing Mandrake doesn't lack is docs, readily available info -- Tom Brinkman [EMAIL PROTECTED] Galveston Bay -- Prana [EMAIL PROTECTED] http://www.cyest.org My GnuPG Key ID: 0x33343FD3 (2000-07-21) Key fingerprint = F1FB 1F76 8866 0F40 A801 D9DA 6BED 6641 3334 3FD3 http://blackhole.pca.dfn.de:11371/pks/lookup?op=getsearch=0x33343FD3
Re: [Cooker] cooking on documentation
Prana wrote: I am sorry if I have walked on someone's toes that was not my intention. When teaching, I knew that I used my personality to try to bring knowledge and that the pupils did not have to like my style, that's life. What I felt about my daughters questions that I found correct was, the lack of a consistent way of presenting all that documentation. What she was nagging about and quite frankly laughed at was four different styles html, man, info and text style in /usr/share/doc. She asked if there was programs that presented man in html and I said that I thought so. Then she said why isn't it used automatically, is this some tribal rite you unix fantasist must undergo when you learn new things. I think she is entitled to her opinion as well as you are of your. regards guran
Re: [Cooker] cooking on documentation
On 2001.02.02 14:29:40 +0400 guran wrote: Prana wrote: I am sorry if I have walked on someone's toes that was not my intention. When teaching, I knew that I used my personality to try to bring knowledge and that the pupils did not have to like my style, that's life. What I felt about my daughters questions that I found correct was, the lack of a consistent way of presenting all that documentation. What she was nagging about and quite frankly laughed at was four different styles html, man, info and text style in /usr/share/doc. You are confusing format and access method here... maybe a bit of simplification : man pages are the traditional unix documentation style, it uses troff as format info pages are the GNU documentation style, it uses info format (not sure about this one) files in /usr/share/doc is package-based distribution style, either in text or html format You could as well add HOWTO to this list, under a variety of format, and KDE and Gnome application specific documentations. Windows, for its part have also several kinds of doc: DOS help (try command /?) Readme.txt everywhere on the system (in wondows dir, in applictation dirs, etc) Windows applications help, in windows help system format. What appears as uniformity here is rather poverty, as lots of things are either undocumented, hard to find (spred everywhere on the disk), or under into proprietary format. If you want the same under linux, just forget everything but KDE/Gnome help system. -- Any system which depends upon human reliability is unreliable -- SNAFU Equations (JB's Scholastic Laws) n2
Re: [Cooker] cooking on documentation
Guillaume Rousse wrote: I don't think this is for real. Everybody on this list seems to have signed a document stating that it is not allowed to post anything that is not bowing to your God Linux. I have been using Linux since 1997 and I don't have any and don't like MS products. The reason I changed is that I had bought a win95 in jan 96 and later that year I was about to upgrade some form of 'package' via modem. Some of my programs were pirate copies like word6. I was confused when MS send me a message on my CRT that they had found word6 on my computer and asked me if I wanted to register it. They had scanned my entire hard drive. As a thief I didn't like that. I know a little of Linux documentation as I have used it. I was referring to how a person, who had never used Linux, looked at in this case the documentation. When I introduced her to man I did it from a console mode under mc. Within mc I showed her how to find /usr/share/doc and opened a file or two. I think that her point was directly at the bulls eye, a newcomer to Linux will try to find all form of relevant documentation under the icon docu. If others do the same then it ought to be a good point to have all documentation easily reached through that icon. If you don't think so, why not say that. Personally I don't give a damned about, in what form the documentation is constructed, I am only interested in the information. If Mandrake is about 'axes made of stone' because that is what Linus used when he started Linux, then I think you are an amish society. For heavens sake, come on, this is most probably about evolution. regards guran
Re: [Cooker] cooking on documentation
On 2001.02.02 16:01:41 +0400 guran wrote: Guillaume Rousse wrote: Dont insert this if you don't want to quote anything of my post. I don't think this is for real. Everybody on this list seems to have signed a document stating that it is not allowed to post anything that is not bowing to your God Linux. As anyone here having said anything like that ? You asked other people opinion, i just gave mine. If you want comparison between windows and Linux, please compare what is comparable. I know a little of Linux documentation as I have used it. I was referring to how a person, who had never used Linux, looked at in this case the documentation. When I introduced her to man I did it from a console mode under mc. Within mc I showed her how to find /usr/share/doc and opened a file or two. When you introduce someone to windows, do you explain it to dir, mkdir, xcopy and all relevant dos commands ? I don't think so, cause peoples use window explorer for such tasks. If you want the same approach on Linux, use KFM or GMC, each one with their relevant help systems, very close to windows help. I think that her point was directly at the bulls eye, a newcomer to Linux will try to find all form of relevant documentation under the icon docu. If others do the same then it ought to be a good point to have all documentation easily reached through that icon. Try to use documentation about dir command from windows help... You only access windows help from here, beacause that's the only doc available, and there is only one environement available. On Linux, you have several environement available, each with its particularity. So several help systems. Guillaume -- The value of a program is proportional to the weight of its output -- Thoreau's Theories of Adaption n7
Re: [Cooker] cooking on documentation
Hi Let us stop this for now. When I quoted my daughter I did it because I thought it was witty, not because I thought that she formulated an eternal truth. From her remarks as a complete newcomer to Linux, I thought that something good or pedagogic could be extracted. I assumed that any other newcomer to Linux might find it simple to be able to reach out to all forms of documents on Linux in one consistent manner through that icon. I still hold that view but we seem to differ. regards guran
RE: [Cooker] cooking on documentation
Let us stop this for now. When I quoted my daughter I did it because I thought it was witty, not because I thought that she formulated an eternal truth. From her remarks as a complete newcomer to Linux, I thought that something good or pedagogic could be extracted. I assumed that any other newcomer to Linux might find it simple to be able to reach out to all forms of documents on Linux in one consistent manner through that icon. I still hold that view but we seem to differ. I personally don't want to stop this thread, because I think your daughter has a valid point and I agree with it. Up until I read your post, I had actually never clicked "Doc". I don't know why, but I hadn't. So I did, and I saw two links there: - Installation Guide and User Guide - Reference Manual Now, if I remember correctly (let me double check with RPM.. yup), I have quite a few pieces of documentation installed.. howto-html-en faq lame lpg (countless others) .. and not to mention everything in /usr/share/doc/. Now, I know where the documentation is (I've learned where to search after 7 years of mucking with Slack, RH, Turbo, and finally Mandrake). But why can't the "Doc" icon provide an easy interface to these items as well? Don't want to have a whole bunch of broken links if they're not installed? Well, put a temporary placeholder where they should be that says something like, "This documentation package is not installed. Please insert your Mandrake CD-ROM and install the blah-blah.rpm package". Man pages, you say? There's quite a few man2html programs out there, I took one and modified it for my own personal use quite a while back. The one I have does it on the fly, so you don't have to have a static set of HTML files. Now, before someone flies off the handle at me with their opinion, take a step back and look at where Mandrake is going, and see where they excel currently, and tell me my logic is incorrect (and please tell me if I'm incorrect): - Mandrake is one of the top-selling Linux distributions in the U.S. retail market (Many people are buying it off the shelves, and I'm sure a good portion of these are people that have never used Linux/UNIX) - Mandrake is one of the easiest distributions to use (Newbies like it because they don't have to get their hands dirty right away, they can install it, use it, and learn it at their own pace, and the GUI is intuitive so they can) - Mandrake gears itself towards new users (I have never seen a Linux distribution work so hard at making something that both hard-core/power users AND new users can use, and use effectively) I think that one of Linux's great faults is lack of organized documentation. The Linux Documentation Project has gone a long way to improving this, but there is still a long way to go. It's now up to the distributions to fill the gaps. Now.. Mandrake developers, on your TODO list, could you please add an item to work on a way of using the "Doc" icon to integrate all the different forms of Linux documentation that you install? I think that's all we're asking for.. Don Head SAIR LCA, CIW-P, Network+, A+ Systems Administrator [ [EMAIL PROTECTED] ] Web Designer[ 1 314 997-7847 ] [ AIM - Don Wave ] [ ICQ - 18804935 ] [ Yahoo - Don_Wave ]
Re: [Cooker] cooking on documentation
Okay, thanks for the nice argumentation, I fully support his nice demand on a central for all documentation. regards guran
RE: [Cooker] cooking on documentation
I'm new on the team, but I agree. Pulling all the various Linux documentation into one comprehensive library would be a very good thing. Like you, I came up the ranks from Slackware, etc., and I know where to look, but for newcomers, the amount of "stuff" on a typical Linux installation can be overwhelming. I thing all the tools we need are out there for conversion/viewing, we just need to index it and pull it all together. Should not be a huge undertaking. I'm adding it to my notebook as something folks would like to see. Stew Benedict On Fri, 2 Feb 2001, Don Head wrote: they're not installed? Well, put a temporary placeholder where they should be that says something like, "This documentation package is not installed. Please insert your Mandrake CD-ROM and install the blah-blah.rpm package". Man pages, you say? There's quite a few man2html programs out there, I took one and modified it for my own personal use quite a while back. The one I have does it on the fly, so you don't have to have a static set of HTML files. Mandrake developers, on your TODO list, could you please add an item to work on a way of using the "Doc" icon to integrate all the different forms of Linux documentation that you install?
Re: [Cooker] cooking on documentation
here is the biggest part of the problem. In KDE the app kppp half of the documentation is "to be done" in a 2.0 release! What needs to happen is hackers need to think about programing for morons even to the point of in a compile the bare Make command should compile EVERYTHING. Yes Docs for console apps are in two different formats BUT THE TWO FORMATS SHOULD MIRROR EACH OTHER. The rule should be Code the Docs , Doc the Codes. Robert L Martin
Re: [Cooker] cooking on documentation
She asked if there was programs that presented man in html and I said that I thought so. Then she said why isn't it used automatically, is this some tribal rite you unix fantasist must undergo when you learn new things. Speaking of which... I'm currently starting a project on sourceforge called php-man-gateway (throw that in front of sourceforge.net to get the homepage). There's really nothing there at the moment except a minimal PHP script that pipes the output of 'man [section] command' through 'col -b' to remove nasties and displays it inside of a pre /pre block. I'm hoping to eventually make a functional alternative to 'man2html' in PHP, with automatic linking to other pages, fun colors and font sizes, and all that type of stuff. As it exists currently, check out http://mattman.dhs.org/man.php for the real thing, man.phps for the source. Hopefully I can get the sourceforge site somewhat functional in a few days, and get development going. Any help would be much appreciated, as this is as much an excercise to teach myself PHP than anything else. Matt _ Get your FREE download of MSN Explorer at http://explorer.msn.com
Re: [Cooker] cooking on documentation
Matt Morrison wrote: Any help would be much appreciated, as this is as much an excercise to teach myself PHP than anything else. Good luck. I love evolution, especially when it is creating new flowers. Wish I could help, I used Modula2 as a hobby some 15 years ago and have now bought a book on ADA95. regards guran
[Cooker] cooking on documentation
Hi The other day I was upgrading my daughters pc, she uses win98, and I added mdk7.2. As an old teacher I showed her were the documentation was situated. She asked me why not all documentation was to be reached more nicely through the icon titled documentation. Her next question was if it was just put there because windows has it, and if Mandrake had not been able to find out why it was there. Isn't this a computer that can do that finding and sorting for me? You Linux guys do not understand the users you are just bragging about what a racing machine Linux is, and understands nothing about how to simplify computing. I could not find a good answer. regards guran
