Subject: web pages

From: Mikhael Goikhman <[email-masked]>
Date: Wed, 9 Apr 2003 02:55:10 +0000

Several notes about web pages.

Autogenerated lines in cvs files is not a good idea.
For example autogenerated Last-Modified-Date or Author or History only
lead to unnecessary cvs conflicts (if 2 people work on different parts of
the same file). This belongs to ChangeLog and/or cvs web interface, not
to a file content. Similarly about cvs variables like $Id, $Log.

The last character of text files in cvs should better be EOLN, otherwise
a probability of cvs conflicts (unnecessarily) grows. Please force whole
lines.

This is not just theoretical issues, I actually got such cvs conflicts.

BTW, in some new pages I used a style that we use for our C/Perl code,
i.e. one TAB for indentation, always a space after a comma and so on.

Finally, I really like a progress in moving to a new design.
I just don't understand yet everything and it seems there are bugs.
I plan to convert manpages and perllib documentation.

Regards,
Mikhael.
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Uwe Pross <[email-masked]>
Date: Wed, 9 Apr 2003 09:57:36 +0200

Hi Mikhael,

> Autogenerated lines in cvs files is not a good idea.

What do you mean by "auto"? In the new version there is not
and it was not planed to autogenerate anything. 

In the new version some file for example author information
or latest news *may* be created from the corresponding
files (AUTHOR, NEWS) in the fvwm tree. I have provided
awk-scripts for this. 

> For example autogenerated Last-Modified-Date 

The new version of the layout file inserts the last
modified date of the actual file automatically. The time
is taken from the file's timestamp on the webserver.

> or Author or History only lead to unnecessary cvs
> conflicts (if 2 people work on different parts of the
> same file).

Since those files are created from the corresponding files
of the fvwm tree, the conflicts should be not too big.

> Similarly about cvs variables like $Id, $Log.

Agree $Id, $Log should not apear in the web files.
 
> The last character of text files in cvs should better be
> EOLN, otherwise a probability of cvs conflicts
> (unnecessarily) grows. Please force whole lines.

I don't see the point here, but I think emacs can do that
automatically. I will have a look how this can be done.

> BTW, in some new pages I used a style that we use for our
> C/Perl code, i.e. one TAB for indentation, always a space
> after a comma and so on.

For indentation I use corresponding modes in emacs. It
indents text automatically. I will check the files
according to this style conventions.

> Finally, I really like a progress in moving to a new

Converting the old html-pages to a w3c-conform html takes
time. Some old pages are far away for standard html:

http://www.mirror.ac.uk/services/validator/check?uri=http%3A%2F%2Fwww-user.tu-chemnitz.de%2F%7Euwp%2Ffvwm-web%2Fcvs.html

I don't like to put broken html on the new page.

> I just don't understand yet everything and it seems there

I hope not ;-)

I did not have time to make a short documentation how the
new php concept works (except a mail addressed to parv and
fvwm-workers a couple of weeks ago) and how new sites are
added/modified on the new web tree. 
I will do that in a while.

Just some notes here:
- You need a php web server which you grants write access
  to the file navgen_write/navigation.inc
- After designing a new page you need to run navgen.php on
  your web server to update the navigation array which is
  stored in the file navgen_write/navigation.inc.
  navgen.php reports warnings and errors on the site
  structure.
  With no errors and warnings the output of navgen should
  look like
  http://www-user.tu-chemnitz.de/~uwp/fvwm-web/navgen.php
  The new version of php provides a command line interface
  which allows to process php-files without a web server.
  To use this CLI with navgen some adaptions are neccessary
  since the environment is different. Im going to change
  navgen so that it runs on a web server and on the CLI.
- After cleaning the problems reported by navgen please
  check your new site with the html and css checker. It
  will tell you what's not html/css-conform on your site.
  BTW: Both of your news sites passed this check :-)

If you just make a new page and commit it without running
navgen. Your site won't work as expected in most cases.

> I plan to convert manpages and perllib documentation.

Actually I am working on the creation of the manpage files
at the moment. At least yesterday night ;-)

The problem is that man2html produces non standard html. I
found a tool http://tidy.sourceforge.net/ which can clean
this html afterwards. 

I planed to write a new script or rewrite the actual script
which makes some further adaption to get a nice manpage
files for the fvwm web site.

Since I might not have time till weekend you could do the
manpage conversion script. 

Please let me know if you are going to do it so that I can
send you some dones, ideas and plannings.

Regards, Uwe
-- 
  ,_,  Uwe Pross
 (O,O) mailto:[email-masked]
 (   ) http://www.tu-chemnitz.de/~uwp
=-"-"-================================
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Mikhael Goikhman <[email-masked]>
Date: Wed, 9 Apr 2003 21:09:23 +0000

> files (AUTHOR, NEWS) in the fvwm tree. I have provided

No, I didn't mean files that are fully generated, only files that are
mostly written by hand but contain lines (meta information) that should
be updated on every file change.

Ideally, all meta information should be outside of the file contents,
but of course there may be exceptions, for example some web pages may
contain text "This page was last updated on XXX" as part of the content.
But this text at least serves some purpose, not is just a comment.

> > I just don't understand yet everything and it seems there

For example, I don't yet understand why sometimes lines inside a
window-based decorations are wrapped as if there is a table that is 30%
or similar of the whole window decoration width.

Also there is a broken layout and uninformative error when there are
consistency problems in $parent and $this on different pages. But you
probably fixed this.

>   to the file navgen_write/navigation.inc

I think you refer to the old php. Let's just suppose everyone has
a new php and thus a command line php utility, so granting any write
access to the web server is not needed.

>   check your new site with the html and css checker.

The problem with this is that you should first commit and only after some
time (it is updated once in several hours) check out fvwm.org or
fvwm.sf.net, because links like "file://..." or "http://localhost/"
can't be checked.

Is there a validator that accepts input (say, as a form field) instead of
url? This is not urgent and not very important at all.

> send you some dones, ideas and plannings.

I planned only to convert html to php, i.e. to continue with man2html.

If you think it is not good enough, you may try tidy. Just, as you
said the current script does dozens of small fixes of both .1 and
the resulting .html, so the output becomes correct and usable.

I also planned to have this structure:

  documentation/manpages - links to stable and unstable, and to perllib
  documentation/manpages/stable - contains man pages of 2.4.x
  documentation/manpages/unstable - contains man pages of 2.5.x

  documentation/perllib - links to stable and unstable, and to manpages
  documentation/perllib/stable - contains man pages of 2.4.x
  documentation/perllib/unstable - contains man pages of 2.5.x

(Should we shorten "documentation" to "doc"?)

Since everything is autogenerated, I see no problems to have both
stable and unstable versions of man pages on the web.

I will wait for your answer about whether you want to try tidy or not
before starting to do this.

Regards,
Mikhael.

---

From: Jason L Tibbitts III <[email-masked]>
Date: 09 Apr 2003 22:43:57 -0500

>>>>> "MG" == Mikhael Goikhman <[email-masked]> writes:

MG> The problem with this is that you should first commit and only
MG> after some time (it is updated once in several hours) check out
MG> fvwm.org or fvwm.sf.net, because links like "file://..." or
MG> "http://localhost/" can't be checked.

The fvwm.org web server pulls from CVS every ten minutes.

 - J<

---

From: Uwe Pross <[email-masked]>
Date: Thu, 10 Apr 2003 08:43:09 +0200

Hi Mikhael,

On 09 Apr 2003 at 21:09:23 +0000, Mikhael Goikhman wrote:

> No, I didn't mean files that are fully generated, only
> files that are mostly written by hand but contain lines
> (meta information) that should be updated on every file
> change.

Do you mean the actual version numbers of fvwm for example?
This may be obtained automatically from fvwm-cvs/ftp or we
place a meta information file in the tree where some
php-variables are set like:
<?php
$stable_version = "2.4.16"
$unstable_version = "2.5.6" 
?>
This file could be included in the php files as needed.

> Ideally, all meta information should be outside of the
> file contents, but of course there may be exceptions, for
> example some web pages may contain text "This page was
> last updated on XXX" as part of the content.

In the actual version the last update time is placed on the
bottom of the page. This time is obtained from the
timestamp of the php file to be displayed. So no need to
place update information in the php itself.

> For example, I don't yet understand why sometimes lines
> inside a window-based decorations are wrapped as if there
> is a table that is 30% or similar of the whole window
> decoration width.

I realized this yesterday when I started porting the module
information page. I fixed it this morning. The table inside
the window decoration did not have a width attribute. I
have set it to 100% which means the contents uses 100% of
the windows width.

> Also there is a broken layout and uninformative error
> when there are consistency problems in $parent and $this
> on different pages. But you probably fixed this.

Navgen fixed this problem silently before. Now a warning is
given if the definitions in parent and child does not
match. Also I removed an error message on the web site if
the actual paged does not belong to the navigation array.
In the actual version the value of $this_page is set to the
first element of the $top_array which is the home page. This
new behaviour avoids displaying unecessary error messages.

> I think you refer to the old php. Let's just suppose
> everyone has a new php and thus a command line php
> utility, so granting any write access to the web server
> is not needed.

Okay. If you think this is not too much restriction I will
try to make navgen run in the CLI environment.

> The problem with this is that you should first commit and
> only after some time (it is updated once in several
> hours) check out fvwm.org or fvwm.sf.net, because links
> like "file://..." or "http://localhost/" can't be
> checked.
> 
> Is there a validator that accepts input (say, as a form
> field) instead of url? This is not urgent and not very
> important at all.

Yes, I got the same problems when I wrote sites at home.

The tidy program is even more restrictive than the web
validator and can be used with wget like:

wget -q -O - http://localhost/fvwm-web/download/index.php | tidy -errors -q

will show you errors on the file. You may want to hide the
links to the validiation pages for this request since they
produce warnings. The links are inserted from
layout_default.inc and may be not inserted when the request
comes from localhost or your host name. Please check this
files the links are hidden for the web checkers already.
You can check which php-variable can be used to hide the links
by viewing the file php_info on your webserver and find out
what is specific to your server.

> If you think it is not good enough, you may try tidy.
> Just, as you said the current script does dozens of small
> fixes of both .1 and the resulting .html, so the output
> becomes correct and usable.

For the first time we can use the current script and run
tidy afterwards. After this we need to replace the header
and footer of the html output and replace it with a php
header and php footer. I wrote templates for this. You
could add the tidy run and the header/footer-exchange to
the current script. 
I planed to extend the current so that certain keywords on
the files will be converted to links to other man pages.
For example all occurences of FvwmTaskBar will be replaced
by a link to the FvwmTaskBar manpage. This is done in all
manpages except the FvwmTaskBar manpage itself.
But this a fancy feature and can wait ;-)

>   documentation/perllib/unstable - contains man pages of 2.5.x

Good idea. No worries. I would like to remove the perlib
documentation from the module information site and place it
separately. 
 
> (Should we shorten "documentation" to "doc"?)

You can do that if you like. I actually prefer long names
for variables and files. I use xemacs which provides a
expand function so that I don't have to write the name each
time. That's why I rather use long names which gives me a
rough idea what the variable/function/file does. But doc is
also expressive ;-)

> Since everything is autogenerated, I see no problems to
> have both stable and unstable versions of man pages on
> the web.

Agree.

> I will wait for your answer about whether you want to try
> tidy or not before starting to do this.

I convert the developers information tree currently. So
it would be nice if you could do the man pages. After this
we should have almost finished it ;-)

BTW: One thing I forgot to mention yesterday. I saw that you
used a identifier containing spaces in your php file like:

//--------------------------------------------------------------------
// Site definitions
//--------------------------------------------------------------------
$title          = "FVWM - Logo Competition";
$heading        = "FVWM - Logo Competition";
$link_name      = "Logo Competition";
$link_picture   = "pictures/icons/logo_competition";
$parent_site    = "news";
$child_sites    = array();
$requested_file = basename(my_get_global("PHP_SELF","SERVER"));
$this_site      = "logo competition";  
                      ^^
The value of $this_site is used as name of a php array.
Navgen would produce php-code like
...
$logo competition["parent_site"] = ...
...
 
Currently navgen does not check if the identifier given in
$this_site are valid.
So the contents of this_site must be a valid identifier
according to programming languages.

I will add a check for this to navgen shortly.

Regards, Uwe

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 15 Apr 2003 01:49:54 +0000

> Do you mean the actual version numbers of fvwm for example?

By meta information I mean the multiline header in all php files.
For example the line: //-  Last modified : <09.04.2003 08:14:03 uwp>
This belongs to the revision control system, it manages it automatically
without a need to store this meta information in the file body itself.

> But this a fancy feature and can wait ;-)

This fancy feature is already done, isn't it? All .B FvwmTaskBar or
.I FvwmTaskBar are replaced with a link to its man page.

> You can do that if you like.

Currently, it is 50/50 for me. Both are good...

> according to programming languages.

Yes, but I didn't use a space here, I used "logo_competition_rules" and
"logo_competition" names, I meant to use the last one in both cases.

Regards,
Mikhael.

---

From: Uwe Pross <[email-masked]>
Date: Tue, 15 Apr 2003 08:37:37 +0200

Hi Mikhael,

On 15 Apr 2003 at 01:49:54 +0000, Mikhael Goikhman wrote:

> For example the line: //- Last modified : <15.04.2003 08:36:53 uwp>
> This belongs to the revision control system, it manages it
> automatically without a need to store this meta information in the
> file body itself.

You are right. I haven't think on the header in the files.
My emacs updates this header automatically each time I save
a buffer. I have removed this line in all files.

> This fancy feature is already done, isn't it? All .B
> FvwmTaskBar or .I FvwmTaskBar are replaced with a link to
> its man page.

I thought I have found some examples where this link was
not made. For example in the FvwmButtons Manpage there is a
"FvwmPager" which is not a link.

> Yes, but I didn't use a space here, I used
> "logo_competition_rules" and "logo_competition" names, I
> meant to use the last one in both cases.

No worries, was just a note. I have thought to remove this
restriction anyway by using a two-dimensional array.

Are you doing the man page conversion for the new web site? 

Regards, Uwe

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 15 Apr 2003 09:10:13 +0000

> Are you doing the man page conversion for the new web site? 

Yes, today or most probably tomorrow.

Regards,
Mikhael.

---

From: Uwe Pross <[email-masked]>
Date: Tue, 15 Apr 2003 11:31:52 +0200

Hi Mikhael,

> Yes, today or most probably tomorrow.

That's good. 

To support passing of different layouts between fvwm-sites relative
links should be done like:

<a href="<?php echo conv_link_target('stable/fvwm_man.php');?>">fvwm</a>

This uses the php-function conv_link_target which must be defined in
the actual layout file. Please check if your pages propagate the
actual layout definition to other pages:

http://www.fvwm.org/documentation/manpages/index.php?layout=plain

I am going to write some developer information on the new website
about the layout interface, html-conventions, image names, .... 
Hopefully I find the time to do that today.

Before that I am going to finish the entry documentation page. This
might be done tonight.

When the man pages and the doc page are ready, we might put the first
version online ;-)

Regards, Uwe

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 15 Apr 2003 10:24:45 +0000

> http://www.fvwm.org/documentation/manpages/index.php?layout=plain

I think it will be much more simple for us and more convenient/consistent
for a user if we don't use/pass GET parameters to define all kinds of
layouts, themes, css-s. Yes, I really mean this. Only use session values
that are valid for the entire site per user. Users with write cookies
turned off only get the default layout or the last stored layout (some
users enable cookies temporarily only to store settings once).

This is a good practice. This way, external sites may link to:

  http://fvwm.org/documentation/manpages/stable/

and different users will see it differently depending on their previous
settings.

I am really concerned about how external and internal links look.
I don't like very much if the links include any GET parameters.

Of course you may optionally implement a logic that if GET parameters are
defined they are used (override) the user settings. But by default no url
should contain these parameters, i.e. normally the user layout should not
be passed in the link.

> When the man pages and the doc page are ready, we might put the first

Probably on April 20 if everything goes well.

Someone should write announcements.

Regards,
Mikhael.

---

From: Uwe Pross <[email-masked]>
Date: Tue, 15 Apr 2003 13:07:07 +0200

Hi Mikhael,

> users enable cookies temporarily only to store settings once).

I don't see any bad issues by passing parameters via url.  This is not
mandatory - It is a feature. I have discussed with Bob about using
cookies about two weeks ago and we agreed to implement it when we have
fot the time. 
For now GET parameters are implemented and can be used. An automatic
selection using cookies should not be that difficult to set up. I
have planned to make a separate page which contains all available
layouts from which the user may decide if he wants do set a cookie. I
don't like to force the user to enable cookies. 

> and different users will see it differently depending on their
> previous settings.

A user which comes from a external site gets the default layout. If he
changes the default settings he may bookmark it or does it again at
next time he views the pages. 

> I don't like very much if the links include any GET parameters.

Changing the layout and keep it changed when viewing subpages is a
feature I haven't seen on any other web site. With the parameters in
the url the user can see how this is been done.

> Of course you may optionally implement a logic that if GET
> parameters are defined they are used (override) the user
> settings. But by default no url should contain these parameters,
> i.e. normally the user layout should not be passed in the link.

The layout defs are only passed in the link if the user has changed it.

Anyway, I think even if we don't use parameter passing via url it is
good to use the wrapper function "conv_link_target" since it makes it
possible to manipulate relative links inside the php-scripts. This
function can just return its argument or append layout definitions as
we wish. 
Further one could generate a html version of the php-tree by changing
the link target from *php to *html and rip the whole tree using wget.

> > When the man pages and the doc page are ready, we might put the
> > first version online ;-)
> 

It should be possible to get all pages ready be this time. But I won't
have any time between 18 and 21 April. 
Removing index.html in the root directory should be the only thing to
do. Maybe we can put a .htaccess file in the root directory which says
the server should serve index.php before index.html, so we can keep
the old version fully. I don't know if the server supports this.

Regards, Uwe

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 15 Apr 2003 12:34:48 +0000

On 15 Apr 2003 13:07:07 +0200, Uwe Pross wrote:
> I don't see any bad issues by passing parameters via url.

Suppose someone wants to post (or include in his site) a link to the
FvwmButtons man page. If he copies it and it has "?layout=something", all
users are forced to read it using this specific layout that some may find
unreadable. This is bad.

Now, suppose he is smart enough to post a link with everything after "?"
stripped. Now all users are forced to see the default layout. This is not
the best thing to do either.

The best possible way IMO is not to have any GET parameters in url and
use stored session values only (if any).

> possible to manipulate relative links inside the php-scripts.

Sure, I have no objections to this.

> the old version fully. I don't know if the server supports this.

Moving index.html to old-index.html would be enough.

One more thing. It would be nice to have 404.php (configured in apache)
that shows an error and suggests to go to the home page. It may also
include a match table that maps the old url to the new one to suggest it.
A possible auto redirection may be used, but this is arguable.

Regards,
Mikhael.

---

From: Uwe Pross <[email-masked]>
Date: Tue, 15 Apr 2003 15:46:55 +0200

Hi there,

> use stored session values only (if any).

How about somebody wants to put a link to the button page with exact
a specific layout?
I think we should support both. By default the user will be asked to
set a cookie to store a layout definition. But we may offer the
possibility to access different layout via GET parameters. Maybe the
user is asked to type this url by hand. If GET parameters are given we
can assume that the user wants a specific layout and use it instead of
default or cookie settings. In that case it may be useful to pass
this parameters to sub pages. (We may also hide the parameters from
the url and store it in a cookie automatically. But I don't like that 
that much.)

For example I often copy bookmark files from home to work or vise
versa.  I could want to have the layout stored in the bookmark or have
it stored in cookie what may be different on the browsers. The same is
if I use the same bookmarks with different browsers. I think it is a
matter of taste.
 
A third possibility is a session function in php. I think in a session
one can pass variables from page to page. It should be intended for
online shops. Since I haven't used it yet I don't know much more. I
will check the php docu and have some tries. It might be not bad.

> A possible auto redirection may be used, but this is arguable.

Does the server return the file /404.php if the requested page is not
on the server? I have to read some apache docu to learn how this works. 

Regards, Uwe

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 15 Apr 2003 18:40:11 +0000

> the url and store it in a cookie automatically. But I don't like that 

I think that this is the best thing to do.

> on the server? I have to read some apache docu to learn how this works. 

It returns the result of whatever is configured in ErrorDocument 404.
It may be configured to use a redirection or a local substitution (this
differs in which url of the missing page a user gets). I prefer a
substitution, i.e. /generated/FAQ.html shows the result of /error/404.php

Regards,
Mikhael.

---

From: Jason L Tibbitts III <[email-masked]>
Date: 15 Apr 2003 14:02:43 -0500

>>>>> "MG" == Mikhael Goikhman <[email-masked]> writes:

MG> It returns the result of whatever is configured in ErrorDocument
MG> 404. It may be configured to use a redirection or a local
MG> substitution (this differs in which url of the missing page a user
MG> gets). I prefer a substitution, i.e. /generated/FAQ.html shows the
MG> result of /error/404.php

You can put "ErrorDocument 404 /some/url" in a .htaccess file and
check that in; it should work.

 - J<