* ZSH presence on WWW cf. Perl @ 1996-03-15 23:56 Mark Borges 1996-03-16 0:12 ` Richard J. Coleman ` (2 more replies) 0 siblings, 3 replies; 10+ messages in thread From: Mark Borges @ 1996-03-15 23:56 UTC (permalink / raw) To: ZSH mailing list [It's late Friday afternoon -- too late to do any real work ] Hey-- Has anyone seen the Perl WWW page lately? It's at http://www.perl.com/perl/ With the release of perl-5.002 came a much better (IMO at least) organization. There are several aspects I like about it -- the broad categories, the update time-stamps, the diversions. I think it could serve as good boilerplate material for zsh. Not that there is anything seriously wrong with the zsh page at present -- it's certainly functional. But I'm getting bored with it. In particular, I'd like to suggest that the baseline documentation be converted to something other than nroff, such as perlpod. Before you yell and flame back, wait... I do think it's very important to have a current, up-to-date, good old man page for zsh; I'm just not convinced nroff is the best source. In fact, after viewing the perl page, I'm far from convinced. The frame interface for the documentation, at ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/doc/manual/html/frames.html -- if your browser/machine can withstand the bombardment -- is pretty powerful for navigating the documentation. (I think Tom had must've had some graduate slavery in addition to pod2html here.) Further, POD is easy to type, which is important because documentation updates would be far more likely to be bundled with the patches. I know, POD is somewhat restrictive on the embellishments you can put in the text, but that's secondary to information content as I see it. And you get pod2man, pod2html, maybe even a pod2texi, for free. Comments anyone? -mb- P.S> Of course, I myself have little time to do work on any of this ;-). ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-15 23:56 ZSH presence on WWW cf. Perl Mark Borges @ 1996-03-16 0:12 ` Richard J. Coleman 1996-03-18 8:30 ` Bas V. de Bakker 1996-03-16 0:27 ` Chris Dean 1996-03-16 6:12 ` Zefram 2 siblings, 1 reply; 10+ messages in thread From: Richard J. Coleman @ 1996-03-16 0:12 UTC (permalink / raw) To: Mark Borges; +Cc: ZSH mailing list > With the release of perl-5.002 came a much better (IMO at least) > organization. There are several aspects I like about it -- the broad > categories, the update time-stamps, the diversions. > > I think it could serve as good boilerplate material for zsh. Not > that there is anything seriously wrong with the zsh page at present > -- it's certainly functional. But I'm getting bored with it. Yes, these pages are very nice. Using them as a base for changes to the zsh web pages is a good idea. > In particular, I'd like to suggest that the baseline documentation be > converted to something other than nroff, such as perlpod. Before you > yell and flame back, wait... I have looked at pod (and SGML, and other things) several times. One of the things I don't like about pod, is that you can't put things like boldface/italics in code examples. The zsh pages uses this quite a bit. I agree that nroff is terrible. I've been thinking maybe it's time to scrap man pages altogether. Put all the documentation into a latex file, and create a nice zsh manual. rc ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-16 0:12 ` Richard J. Coleman @ 1996-03-18 8:30 ` Bas V. de Bakker 1996-03-18 8:47 ` Peter Stephenson 1996-03-18 15:44 ` Vidiot 0 siblings, 2 replies; 10+ messages in thread From: Bas V. de Bakker @ 1996-03-18 8:30 UTC (permalink / raw) To: zsh-workers "Richard J Coleman" <coleman@math.gatech.edu> writes: > I agree that nroff is terrible. I've been thinking maybe it's time > to scrap man pages altogether. Put all the documentation into a > latex file, and create a nice zsh manual. I like to have documentation on-line as well. But every time I proposed keeping only the texinfo file, there were loud protests from various people. I don't remember exactly why, probably because they had nothing to read info with. Bas. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-18 8:30 ` Bas V. de Bakker @ 1996-03-18 8:47 ` Peter Stephenson 1996-03-18 15:44 ` Vidiot 1 sibling, 0 replies; 10+ messages in thread From: Peter Stephenson @ 1996-03-18 8:47 UTC (permalink / raw) To: zsh-workers bas@astro.uva.nl wrote: > "Richard J Coleman" <coleman@math.gatech.edu> writes: > > > I agree that nroff is terrible. I've been thinking maybe it's time > > to scrap man pages altogether. Put all the documentation into a > > latex file, and create a nice zsh manual. > > I like to have documentation on-line as well. But every time I > proposed keeping only the texinfo file, there were loud protests from > various people. I don't remember exactly why, probably because they > had nothing to read info with. One of the things I hate about systems that other people have set up is finding there's no detailed documentation for (say) elm because the only thing that got installed was a minimal manual page which points you somewhere else, which might be on the machine in the directory /usr/local/.hidden/.even_more_hidden/doc/dunno_where_to_put_this/elm but might not be. Only ordinary manual pages have a reasonable probability of being installed by the average system administrator, who has typically got better things to do than create new directory structures for non-standard manual formats. Even if you arrange for info files to be installed automatically you have to rely on the administrator not only providing an info reader but also changing the `dir' file or even writing a new one --- although a decent script should be able to handle this. On the other hand, nroff is the worst format I can think of for a standard. It would be much better to have something which converts easily into nroff. I don't know of anything reliable and powerful enough at the moment. -- Peter Stephenson <pws@ifh.de> Tel: +49 33762 77366 WWW: http://www.ifh.de/~pws/ Fax: +49 33762 77330 Deutches Electronen-Synchrotron --- Institut fuer Hochenergiephysik Zeuthen DESY-IfH, 15735 Zeuthen, Germany. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-18 8:30 ` Bas V. de Bakker 1996-03-18 8:47 ` Peter Stephenson @ 1996-03-18 15:44 ` Vidiot 1 sibling, 0 replies; 10+ messages in thread From: Vidiot @ 1996-03-18 15:44 UTC (permalink / raw) To: zsh-workers < <"Richard J Coleman" <coleman@math.gatech.edu> writes: < <> I agree that nroff is terrible. I've been thinking maybe it's time <> to scrap man pages altogether. Put all the documentation into a <> latex file, and create a nice zsh manual. < <I like to have documentation on-line as well. But every time I <proposed keeping only the texinfo file, there were loud protests from <various people. I don't remember exactly why, probably because they <had nothing to read info with. < <Bas. Bingo. Man pages are the way to get info on Unix programs. Trying to tell a user that there are TWO ways to find out how a program works will not go over very well. Nroff man pages are here to stay. MB -- System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/> e-mail: brown@ftms.com phone: (608) 273-8262 fax: (608) 273-8719 voice-mail: (800) 538-7067 ext 8451 Visit - <URL:http://www.cdsnet.net/vidiot/> (Your link to Star Trek and UPN) ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-15 23:56 ZSH presence on WWW cf. Perl Mark Borges 1996-03-16 0:12 ` Richard J. Coleman @ 1996-03-16 0:27 ` Chris Dean 1996-03-16 6:12 ` Zefram 2 siblings, 0 replies; 10+ messages in thread From: Chris Dean @ 1996-03-16 0:27 UTC (permalink / raw) To: ZSH mailing list; +Cc: Mark Borges Mark Borges <mdb@cdc.noaa.gov> writes: > Has anyone seen the Perl WWW page lately? It's at > > http://www.perl.com/perl/ Yes, it's very good. > In particular, I'd like to suggest that the baseline documentation be > converted to something other than nroff, such as perlpod. This seems like a great idea. I've been writing a lot (for me at least) documentation recently using perlpod and am quite taken with it. It is so easy to make simple pages that I find myself actually giving my end users documentation much quicker than I used to. In the past I used TeX, but that made it difficult to distribute online documentation. The caveat is that perlpod's "intent is simplicity, not power", and that you can't do complex things. We should also provide a zsh*.man as well as a zsh*.pod for those people who don't have Perl installed. > And you get pod2man, pod2html, maybe even a pod2texi, for free. As of today the pod2texi isn't very usable. Chris Dean ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-15 23:56 ZSH presence on WWW cf. Perl Mark Borges 1996-03-16 0:12 ` Richard J. Coleman 1996-03-16 0:27 ` Chris Dean @ 1996-03-16 6:12 ` Zefram 1996-03-18 8:21 ` Bas V. de Bakker 2 siblings, 1 reply; 10+ messages in thread From: Zefram @ 1996-03-16 6:12 UTC (permalink / raw) To: Mark Borges; +Cc: zsh-workers [on Perl POD] >Further, POD is easy to type, which is important because documentation >updates would be far more likely to be bundled with the patches. We already tend to get man page updates, when necessary, with code patches. The cases where we don't I think are more due to people forgetting than to the difficulty of using nroff. Editing nroff source is not difficult. >And you get pod2man, pod2html, maybe even a pod2texi, for free. pod2man would get us a man page, which we already have, and would do a worse job of it than we would. HTML is irrelevant. pod2texi would let us produce a printed manual, which can already be done from nroff, or an info file, which is also irrelevant. I don't see the advantage here. -zefram ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-16 6:12 ` Zefram @ 1996-03-18 8:21 ` Bas V. de Bakker 1996-03-18 9:07 ` Zefram 0 siblings, 1 reply; 10+ messages in thread From: Bas V. de Bakker @ 1996-03-18 8:21 UTC (permalink / raw) To: zsh-workers Zefram <A.Main@dcs.warwick.ac.uk> writes: [quoted out of context] > HTML is irrelevant. > an info file, which is also irrelevant. Could you explain this? I think info files are quite useful. IMHO, they are easier to navigate than long man pages, whether those man pages are split or not. Bas. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-18 8:21 ` Bas V. de Bakker @ 1996-03-18 9:07 ` Zefram 1996-03-18 19:47 ` Mark Borges 0 siblings, 1 reply; 10+ messages in thread From: Zefram @ 1996-03-18 9:07 UTC (permalink / raw) To: Bas V. de Bakker; +Cc: zsh-workers >Zefram <A.Main@dcs.warwick.ac.uk> writes: > >[quoted out of context] >> HTML is irrelevant. >> an info file, which is also irrelevant. > >Could you explain this? I think info files are quite useful. IMHO, >they are easier to navigate than long man pages, whether those man >pages are split or not. It may be useful, but it's not directly relevant to this discussion. We're discussing documentation for a Unix shell, so the primary requirement is that we have online documentation in the form of a Unix man page. Info is an unnecessary extra. HTML is even less useful. Automated conversion to TeX or LaTeX, however, is of some use, as a nice printed manual would be a good thing. (But it is possible to simply print the man page anyway.) -zefram ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: ZSH presence on WWW cf. Perl 1996-03-18 9:07 ` Zefram @ 1996-03-18 19:47 ` Mark Borges 0 siblings, 0 replies; 10+ messages in thread From: Mark Borges @ 1996-03-18 19:47 UTC (permalink / raw) To: zsh-workers >> On Mon, 18 Mar 1996 09:07:59 +0000 (GMT), >> Zefram (Z) wrote: >> Zefram <A.Main@dcs.warwick.ac.uk> writes: >> >> [quoted out of context] >> HTML is irrelevant. ?? Zefram, can you define what you mean by "irrelevant" here? How do you judge whether something is irrelevant? By tradition? Or functionality? Or demonstrated use? What? I'm not particularly fond of HTML myself, but it is a workable tool that makes some documentation easier to navigate. Certainly you'd agree it's much harder to find a particular piece of emacs documentation using `man' than info (were a complete man page for emacs to exist, that is). Many vendors (MATLAB, NCAR Graphics to name a couple) provide HTML documentation online, because they apparently realize that web browsers, if not prevalent already, will be or are readily available. Whether zsh documentation fits into this category remains to be answered. The length of the documentation is somewhat in-between a clear demarcation. >> an info file, which is also irrelevant. >> >> Could you explain this? I think info files are quite useful. >> IMHO, they are easier to navigate than long man pages, whether >> those man pages are split or not. Z> It may be useful, but it's not directly relevant to this Z> discussion. We're discussing documentation for a Unix shell, so Z> the primary requirement is that we have online documentation in the Z> form of a Unix man page. Info is an unnecessary extra. HTML is Z> even less useful. Automated conversion to TeX or LaTeX, however, Z> is of some use, ...and impossible. AFAIK, there is no automated "man2texi" tool. And *if* we want to make current, up-to-date HTML docs, there is also no automated "man2html" tool. This latter is important, because I personally will not be converting nroff source to HTML. I know about `rman', but it does a far from perfect job on the zsh nroff source. I know, because that's how the current (and obsolete) HTML documentation was created in the first place. I just simply don't have the time to do this anymore (so answering `no' to the first sentence would be OK with me). And for the record, I *never* stated that nroff man pages should not be supported. In fact, I believe nroff source should be *required* for any unix utility (and I would categorize shells as unix utilities for this discussion). Note that Tom Christiansen, who helped develop perl, absolutely detests unix programs without proper (read nroff source) documentation. (He also detests emacs, but that's another thread ;-) ). Yet, you will find no nroff-source documentation for perl; the baseline docs are written in perl-pod, and converted when necessary. BTW, what language has more $#@<!%*>[{+ characters than perl? The pod2man-converted perl man page still gets the information across, by having these characters stand out in other ways besides embellishing them. I don't think a death blow to pod should be dealt just because (for example) some characters cannot appear in bold face very easily. Or is there some other limiting factor of pod that makes it utterly unusable for zsh documentation that I'm unaware of? Examples? I guess we need to answer the elegance/functionality aspect of the zsh man page once and for all, and then take it from there. If we must have the current typesetting of the zsh man page (or something even prettier) I guess pod is out. Finally, here are some crude numbers for the past month access of the man page documentation at the ZSH web site: $ egrep 'Feb/1996.*zsh/Doc/man' /WWW/httpd/logs/access_log | wc -l 657 and for comparison, $ egrep 'Feb/1996.*zsh/FAQ' /WWW/httpd/logs/access_log | wc -l 601 So, despite the out-of-date man page, some people (cats? ;-^) are using the on-line docs. (I can refine these numbers more if anyone wants history and/or access by subsection, etc. to debate some more. There is 38Mb of access data available to parse). OK. Enough rambling. I just wanted to hopefully make my views and position a bit more clear. -mb- ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~1996-03-18 20:03 UTC | newest] Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 1996-03-15 23:56 ZSH presence on WWW cf. Perl Mark Borges 1996-03-16 0:12 ` Richard J. Coleman 1996-03-18 8:30 ` Bas V. de Bakker 1996-03-18 8:47 ` Peter Stephenson 1996-03-18 15:44 ` Vidiot 1996-03-16 0:27 ` Chris Dean 1996-03-16 6:12 ` Zefram 1996-03-18 8:21 ` Bas V. de Bakker 1996-03-18 9:07 ` Zefram 1996-03-18 19:47 ` Mark Borges
Code repositories for project(s) associated with this public inbox https://git.vuxu.org/mirror/zsh/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).