[9fans] complaints about new web site

[9fans] complaints about new web site

[Russ Cox]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 6472 bytes --]

It's probably a very good sign that the only actual complaints we've
gotten about the web site have been about how ugly the HTML
source is.  Hopefully that's the biggest problem it has.

The web site is generated from troff sources by a new program
called htmlroff, which I mentioned in an earlier post and which
will appear on sources once I document it.  Representative commands
are:

	htmlroff -mhtml glenda.tr >glenda.html
	pic utf.ms | tbl | eqn | htmlroff -ms -mhtml >utf.html

There are very small changes to the ms macros to accomodate htmlroff,
but for the most part it can make do with regular troff input.
Htmlroff does allow longer macro, string, and number names, in the
style of groff, so that it is easier to avoid stepping on regular troff
names.

The documents themselves hardly changed:

	% yesterday -d -0101 sam.ms
	diff -n /n/dump/2006/0101/sys/doc/sam/sam.ms /sys/doc/sam/sam.ms
	/n/dump/2006/0101/sys/doc/sam/sam.ms:0 a /sys/doc/sam/sam.ms:1
	> .HTML "The Text Editor sam
	/n/dump/2006/0101/sys/doc/sam/sam.ms:21 a /sys/doc/sam/sam.ms:23,26
	> .de XP
	> .ie h .html - <center><img src="sam.\\$1.png" /></center>
	> .el .BP \\$1.ps \\$2
	> ..
	/n/dump/2006/0101/sys/doc/sam/sam.ms:258 c /sys/doc/sam/sam.ms:263
	< .BP fig1.ps 3.5i
	---
	> .XP fig1 3.5i
	/n/dump/2006/0101/sys/doc/sam/sam.ms:1275 c /sys/doc/sam/sam.ms:1280
	< .BP fig3.ps 2.04i
	---
	> .XP fig3 2.04i
	/n/dump/2006/0101/sys/doc/sam/sam.ms:1360 c /sys/doc/sam/sam.ms:1365
	< .BP fig2.ps 2.74i
	---
	> .XP fig2 2.74i
	/n/dump/2006/0101/sys/doc/sam/sam.ms:1452 c /sys/doc/sam/sam.ms:1457
	< .BP fig4.ps 1.20i
	---
	> .XP fig4 1.20i
	% 

is typical.

> however the source (troff and html) looks terrible

The whole point of having computer-generated HTML is that you don't
ever have to see it.  Yes it looks terrible, but it looked terrible before too.
Even if you run it through tidy or some other HTML reformatted, it will
still look terrible!  You get seduced by the pretty formatting into thinking
it doesn't.  Format this:

	<a href="/magic/man2html/1/cat">cat</a><i>(1)</i>

however you want, but the fact remains that I shouldn't have to scribble
that whole thing out every single time I refer to a man page.  
When I put htmlroff on sources, if someone wants to make the HTML
output look prettier inside, then have at it.

Troff, on the other hand, is just as arcane but lets you build up to 
what you're trying to get done.  Yes, the troff versions do look like troff,
but once you get past that, you get some significant benefits. 
Most important, I can write macros to avoid writing out things like
the above.  So I can write

	.MAN cat 1

which is many times nicer and doesn't need to be changed when
the format or the URL of a manual page reference changes.

Look, for example, at http://plan9.bell-labs.com/plan9/glenda.tr:

	.so macs
	.HTML "Glenda, the Plan 9 Bunny
	.TL
	Glenda, the Plan 9 Bunny
	.PP
	.html - <center><img src="img/9logo.jpg" alt="Logo" />
	.PP
	The logo above is scanned from the original drawing of Glenda,
	the Plan 9 bunny, and appears on your screen at roughly the size
	of the original drawing.
	.HR http://www.reneefrench.com/ "Renée French
	drew Glenda.  When we needed higher-resolution
	drawings, she made a much larger drawing,
	which was scanned, tweaked, and made into two versions,
	one with a white background and one with a black background.
	High-resolution JPEGs of these versions are available by clicking
	on the images below.
	.PP
	Feel free to use these images to make t-shirts and other paraphernalia,
	but if you do a production run, please send us a sample for our collection.
	.PP
	.sp 2
	.html t <center><table><tr>
	.de td
	.html - <td><a href="/plan9/img/\\$1.jpg">\
		<img src="/plan9/img/\\$2.jpg" alt="\\$3" border=0 />
	..
	.td plan9bunnywhite plan9bunnysmwhite "White Bunny
	.td plan9bunnyblack plan9bunnysmblack "Black Bunny
	.td spaceglenda300 spaceglenda37 "Space Bunny
	.html t

or http://plan9.bell-labs.com/plan9/screenshot.tr:

	.so macs
	.HTML "Plan 9 Screen Shot
	.TL
	Plan 9 Screen Shot
	.PP
	.html - <center><a href="img/screenshot.gif">\
		<img src="img/screenshot-small.png" alt="Screen Shot" />
	.sp
	.PP
	This is a 1024x768 screen in 8-bit colormapped mode.
	.sp
	A multi-level MIME message containing a JPEG has just arrived; the structure
	of the message is visible in the Acme mail directory on the right-hand side.
	The graphical programs displayed are:
	the mail announcer
	.MAN faces 1 ,
	the system statistics watcher
	.MAN stats 8 ,
	the text editor
	.MAN acme 1 ,
	the sky catalog
	.MAN scat 1 ,
	the image viewer
	.MAN page 1
	(showing
	.HR glenda.html glenda ),
	and the window system
	.MAN rio 1 .
	Acme is running Mail, which uses the mail file system
	.HR /magic/man2html/4/upasfs \fIupas/fs\fP(4).
	Acme is also editing the
	.HR /magic/man2html/6/plumb \fIrules\fP
	for 
	.MAN plumber 4 .
	.sp
	Additional screen shots are linked on the
	.HR /wiki/plan9/screenshots wiki .

and since the pages all share the same macros, they have a consistent look.

Also, I don't have to write HTML tags, and more importantly I don't have to
close them.  The general form of the .html macro used above is:

	.html id <any html>

It prints <any html> and remembers that the HTML is open.  The next
.html id line will close the corresponding HTML (with the same id!)
before printing anything new.  The special case of id = "-" means 
close immediately.  So for example the ".html t" that ends 
glenda.tr closes the center and table tags that opened earlier.

If the web pages don't look right in some browser, then I'm
happy to accomodate that.  Like Opera:

> Nixing the <center> and having
> 
> <table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr>
> <td align="center" valign="top">
> <pre>
> [...]
> 
> would probably fix it.  The <center> tag is deprecated nowadays anyway.

The <center> tag isn't the problem.  Opera is broken.  If I do this:

	<table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr>
	<td align="center" valign="top">
	<pre>

then Opera still centers the text inside the <pre>!  You have to use:

	<table width="100%" cellspacing=0 border=0><tr><td align="center">
	<table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr><td align="left">
	<pre>

to make Opera center a block. 

Russ

[9fans] complaints about new web site

[erik quanstrom]

"Russ Cox" <rsc@swtch.com> writes

| 
| It's probably a very good sign that the only actual complaints we've
| gotten about the web site have been about how ugly the HTML
| source is.  Hopefully that's the biggest problem it has.
| 
| The web site is generated from troff sources by a new program
| called htmlroff, which I mentioned in an earlier post and which
| will appear on sources once I document it.  Representative commands
| are:
| 
| 	htmlroff -mhtml glenda.tr >glenda.html
| 	pic utf.ms | tbl | eqn | htmlroff -ms -mhtml >utf.html
| 
| [more good info]

russ, this is pretty^wvery cool. 

| If the web pages don't look right in some browser, then I'm
| happy to accomodate that.  Like Opera:
| 
| > Nixing the <center> and having
| > 
| > <table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr>
| > <td align="center" valign="top">
| > <pre>
| > [...]
| > 
| > would probably fix it.  The <center> tag is deprecated nowadays anyway.
| 
| The <center> tag isn't the problem.  Opera is broken.  If I do this:
| 
| 	<table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr>
| 	<td align="center" valign="top">
| 	<pre>
| 
| then Opera still centers the text inside the <pre>!  You have to use:
| 
| 	<table width="100%" cellspacing=0 border=0><tr><td align="center">
| 	<table cellspacing=0 cellpadding=5 bgcolor="#eeeeff"><tr><td align="left">
| 	<pre>
| 
| to make Opera center a block. 

opera may be broken, but it does an okay job of organizing its own windows.
firefox tabs allow me one page at a time, like screens for the web.

if this fix works with other browsers too, it might be nice if it were used.

- erik

Re: [9fans] complaints about new web site

[Sascha Retzki]

On Fri, Jan 27, 2006 at 12:21:10PM -0500, Russ Cox wrote:
> It's probably a very good sign that the only actual complaints we've
> gotten about the web site have been about how ugly the HTML
> source is.  Hopefully that's the biggest problem it has.
> 

Yes, I am very pleased by the new design - good work.

However, one thing (uriel also used to raved about): Can you explain the
need for the "Additional Software"-page? It looks full of outdated,
depreciated software and/or duplicating/confusing things (like the first
download is (seems to be?) a link to the ISO-Image). At least the name
could be renamed to "Additional Software [not included in sources or
outdated]" or alike.


With best regards,


Sascha Retzki

Re: [9fans] complaints about new web site

[Russ Cox]

> On Fri, Jan 27, 2006 at 12:21:10PM -0500, Russ Cox wrote:
> > It's probably a very good sign that the only actual complaints we've
> > gotten about the web site have been about how ugly the HTML
> > source is.  Hopefully that's the biggest problem it has.
> >
> 
> Yes, I am very pleased by the new design - good work.
> 
> However, one thing (uriel also used to raved about): Can you explain the
> need for the "Additional Software"-page?  It looks full of outdated,
> depreciated software and/or duplicating/confusing things (like the first
> download is (seems to be?) a link to the ISO-Image).  At least the name
> could be renamed to "Additional Software [not included in sources or
> outdated]" or alike.

The details of the page may change, but I believe there should
be a page listing the major software packages that people 
commonly want - tex, perl, python, gcc, ...

I cleaned it up a little just now.  

Russ

Re: [9fans] complaints about new web site

[Sascha Retzki]

On Fri, Jan 27, 2006 at 02:04:19PM -0500, Russ Cox wrote:
> > On Fri, Jan 27, 2006 at 12:21:10PM -0500, Russ Cox wrote:
> > > It's probably a very good sign that the only actual complaints we've
> > > gotten about the web site have been about how ugly the HTML
> > > source is.  Hopefully that's the biggest problem it has.
> > >
> > 
> > Yes, I am very pleased by the new design - good work.
> > 
> > However, one thing (uriel also used to raved about): Can you explain the
> > need for the "Additional Software"-page?  It looks full of outdated,
> > depreciated software and/or duplicating/confusing things (like the first
> > download is (seems to be?) a link to the ISO-Image).  At least the name
> > could be renamed to "Additional Software [not included in sources or
> > outdated]" or alike.
> 
> The details of the page may change, but I believe there should
> be a page listing the major software packages that people 
> commonly want - tex, perl, python, gcc, ...

Yeah but there are two major issues:

1.) We create two places to look for software (sources and web)

2.) It may be stuff _new_ people commonly want - I don't want GCC on
Plan 9. And those people probably don't really want GCC either.


Don't misunderstand me, I don't want to imply in any way that the
porting afforts of several people should not be honored in any way - I
am not saying that the work that has already been done, without debating
if it was good or bad work, should be deleted or alike. I am just saying
that we have a clean, good, reliable way of distributing (3rd-party)
additional software - sources. 


I mean, look at the page now. If you are a new user, where do you expect
e.g. software to play an OGG-File: Under "browse the source" (respective
reading papers, the wiki, and getting an idea that Plan9 is way
different than other OSes) or do you click on "Additional Software",
finding GCC, Python and X11?


But honestly, the situation improved with the two page updates.


Sascha
> 
> I cleaned it up a little just now.  
> 
> Russ
> 

Re: [9fans] complaints about new web site

[Russ Cox]

> 1.) We create two places to look for software (sources and web)
> 
> 2.) It may be stuff _new_ people commonly want - I don't want GCC on
> Plan 9.  And those people probably don't really want GCC either.

No one really wants gcc.  But TeX was the original "additional software"
and it remains useful and worth being easy to find.  So is Python.  

Everything on the additional software page is links to sources,
so there's really only one place to find the archives.  There's also
only one real place to look for software, and that's the web page,
unless you like reading large unsorted lists of software packages.
(What Uriel has built is not an index.  It is a table of contents.
A real index would actually help a lot.)

Russ

Re: [9fans] complaints about new web site

[uriel]

>> 1.) We create two places to look for software (sources and web)
>> 
>> 2.) It may be stuff _new_ people commonly want - I don't want GCC on
>> Plan 9.  And those people probably don't really want GCC either.
> 
> No one really wants gcc.  But TeX was the original "additional software"
> and it remains useful and worth being easy to find.  So is Python.
I agree that there are various important packages that should be
listed in a convenient place, I'm working in a new version of the
'Software for Plan 9' wiki page that will(I hope) replace the
"Additional software" page.  First step is to get everyone with
various code bits in random pages over the net to move them to sources
so I can delete the external links.


> Everything on the additional software page is links to sources,
> so there's really only one place to find the archives.  There's also
> only one real place to look for software, and that's the web page,
> unless you like reading large unsorted lists of software packages.
> (What Uriel has built is not an index.  It is a table of contents.
> A real index would actually help a lot.)
The "Contrib Index"[1] is far from perfect, but I think it's still
quite useful.  Any ideas about how to improve it without involving too
much manual work which would ensure its fast obsolescence?


Allowing to tag packages with some kind of category might be good,
probably by having a list of common directory names(eg., 'scripts',
'ports', 'games, 'drivers', etc.,), only problem is to get everyone
with sources accounts to take the time and care to organize their
packages according to those conventions.

Thanks

uriel

[1] Thanks to everyone that moved their code to sources
http://plan9.bell-labs.com/wiki/plan9/Contrib_index/