Re: I want more <div>s to work on :)

[Davi Leal]

Victor Engmark wrote:
> Here's a new version of the Hackers` guide. Some notes:
>

>    - Substantially reduced size.

This is always good.


>    - You don't need an <a> element to use anchor links

Very cool!


>    - There was a lot of empty space, but I guess that's in order to have
>    nicer looking code.

About the HTML code?. Yes. When you add the {t} tabs it gets complexity,
which I tryed to reduce adding empty lines etc.


>    - Somebody should add @titles where not defined already.

Adding titles is very cool, but it is more work for the translators. Note
we lack a French maintainer.


>    - Markup comments which are not for users (such as "XXX Update this
>    image") should probably be code comments or Savannah tasks instead.

I think this one ""XXX Update this image" should be a Savannah task with
very very low priority, and to be realized after the Klaus' architecture
moves to production. To avoid duplication of work.


>    - Chapter count numbers can be arranged with CSS (Doesn't work in IE,
>    but who's gonna notice that on a developer page?).

I agree with you.


>    - Removed "Back to top" links - From what I see around the web, these
>    are not much used. Also makes for less text.

I use they a lot on FireFox, and they are essential on mobile devices to
avoid scrolling!.  I have read it in one of the links you have posted.


>    - Whitespace in <pre> is significant.

I have to check how both look tonight.


>    - Tried to make some of the text more terse. It should have the same
>    information content, but should be reviewed.

I will check it. If it has the same information, I think we will not have
to change the translations of that english sentences again. :)


>    - Moved the PostgreSQL configuration section below the general
>    configuration instructions. Maybe all configuration instructions should be
>    in the same section?

Cool!. I will do the same with the Index entries before sending you the
<div>.


>    - Made shorter IDs.

Cool.


>    - Added <abbr> with no @title for repetitions of already defined
>    abbreviations, like at gnu.org.

Cool.


>    - Used AFAIK more semantically correct quote signs, apostrophes, and
>    such, copied from the XHTML Character Entity

Is it needed?. The server is sending UTF-8?. Anyway, it is truth that at
URL links I had to add  &amp;  to pass the validator.


>    - It would be great if someone has a better link to a howto for
>    ssh-agent.

Please, if you can, add a Savannah task to take note of it.


>    - Removed the "web site" section, since it only points to the web
>    site.

I agree with you.


>    - Removed shell output in favor of just the input from the user. That
>    way, most of the configuration shell instructions can just be copied
>    verbatim and executed.

I agree with you. Maybe we can even remove more of that text. I will take
a look these days.


>    - I took the liberty of removing the source code section
>       - It`s already explained in the introduction.
>       - There`s a warning that the package is probably outdated.

I will send you additional notes about the removed "source code section"
tonight or later.


>       - The flags bit should probably be part of the coding standard
>         (if necessary). By the way, are all todo items marked literally
>         "XXX"?

I agree it should be in the coding standard.  I think the XXX and TODO
flags are standard the facto. Anyway, if the coding standard we use does
not include that note, I think we could leave that sentence as it is now.


>    - Maybe we should split the page into several? I'd suggest the
>      following structure:
>      - Introduction
>      - Installation and configuration
>      - Help / other

I disagree. The page is large, but with "Back to top" it will be OK, as
the current one.



Note:  About the UTF-8 section, I think we must just advice to install and
use UTF-8 as de default encoding in the system.  So the developers get
less troubles.

I will process this XHTML file, and send back to you as <div> with {t}
tabs etc., so you can take a second look.

P.S.: As usual, we could send any comment about this subject later, at any
time.

Davi