www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - D documentation - minor flaws?

reply "Bob W" <nospam aol.com> writes:
First of all, I quite like the D documentation which
is most useful since it is bundled together with
the compiler downloads and thus available for
easy offline reading.

There are just a few omissions/inconsistencies
I'd like to mention, although I do not believe
that any of them needs to be addressed very
urgently:



1) Broken links (page = "dlinks.html"):

tdpl.gif
davisBW.jpg
davisColor.jpg



2) I remember a newsgroup post where Walter ruled
out the use of Javascript on the D documentation
pages (I fully agree with that approach). But I
have nevertheless found occurrences of Javascript
code, which won't display by default on pages
located on a local hard drive due to security
restrictions (latest releases of IE and XP - don't
know about others).

Page "comparison.html" contains an email address
obfuscator written in Javascript, which could be
replaced with a link to an external digitalmars.com
page. (This was recently done in a similar manner
with the search links on the D docs pages.)



3) Another Javascript piece of code appears on the
bottom of the "intro.html" page. Since this is a
Google ad and therefore a probable revenue generator
it might not get removed easily. But this too won't
display by default in IE anyway.



4) All the D docs pages have the BODY tag set to
bgcolor="white". This will override the default
browser's background color. If this feature is
intentional, it should be noted that e.g.
text="black" is consequently needed to ensure
that the intended text/background combination
stays intact. It would prevent the very unlikely
but possible situation of white or light text on
white background.



5) The only exception to the bgcolor="white" BODY
tags seems to be on page "dlinks.html", which does
not specify a background color at all.

I can imagine both: this page being modified in
accordance to the rest of the docs pages

-OR-

let pages be displayed according to browser's settings:
Less pretty on certain systems but more versatile.
This would require to omit specifying bgcolor on all
other pages.

-OR-

my favourite: us one common CSS file to specify
text and background defaults for all pages containing
just one line like that one:

  body {color:black; background-color:white}

This will display web based pages as intended
but their offline counterparts are easily modifiable
once a new compiler version (with docs) is
downloaded.
Apr 12 2005
next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Bob W wrote:
<snip>

 my favourite: us one common CSS file to specify
 text and background defaults for all pages containing
 just one line like that one:
 
   body {color:black; background-color:white}


<snip>

Why bother setting any default background at all?  Overriding user prefs 
with the 'default grey' is hardly putting a personal touch to anything.

Moreover, this'll still screw up if one of the user's default link 
colours is white.

Stewart.

-- 
My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Apr 12 2005
parent "Bob W" <nospam aol.com> writes:
"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message 
news:d3g8uv$2ajk$1 digitaldaemon.com...

 Bob W wrote:
 <snip>

 my favourite: us one common CSS file to specify
 text and background defaults for all pages containing
 just one line like that one:

   body {color:black; background-color:white}


 <snip>

 Why bother setting any default background at all?  Overriding user prefs 
 with the 'default grey' is hardly putting a personal touch to anything.


I agree (mentioned in my post). The CSS suggestion was
purely selfish in nature, because I usually like to invert
displays wherever possible. My perception is that white
background just puts too much strain on my eyes when
reading for prolonged periods of time (I also would not
want to keep staring into lightbulbs).

It seems pretty easy to copy my own D-doc-specific
CSS file to the directiory every time after downloading
a new release.

But at the moment a little D application is modifying the
html files in the D doc directory for me, so I will survive
without a CSS file.



 Moreover, this'll still screw up if one of the user's default link colours 
 is white.


Sure it will, but that does not bother me (selfish again).
Apr 12 2005
prev sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Bob W wrote:


 First of all, I quite like the D documentation which
 is most useful since it is bundled together with
 the compiler downloads and thus available for
 easy offline reading.  [...]


I agree, it's useful (especially when digitalmars.com
goes down, as it did the other day) Have one addition:

I have converted my local D pages to XHTML and CSS,
but it is not available as it is non-distributable...


Here are the HTML markup errors, that Tidy* encountered:
http://www.algonet.se/~afb/d/errors.txt (it fixed them too)

Currently, I am using this CSS stylesheet to display them:
http://www.w3.org/StyleSheets/Core/stylebot.html?family=8&doc=Sampler


Walter has requested to use the Wiki4D for doc suggestions:
http://www.prowiki.org/wiki4d/wiki.cgi?DocComments

And I'll probably resend my converted docs to him, some day.
Maybe I can get a free copy of DMD 1.0 in return ? :-)

--anders


PS. * Tidy is available from http://tidy.sourceforge.net/
Apr 12 2005
parent "Bob W" <nospam aol.com> writes:
"Anders F Björklund" <afb algonet.se> wrote in message 
news:d3g9ds$2apd$1 digitaldaemon.com...

 Bob W wrote:



 Here are the HTML markup errors, that Tidy* encountered:
 http://www.algonet.se/~afb/d/errors.txt (it fixed them too)


Good tool and I wish more web authors would use it. I cannot
remember to have seen any syntactically correct web page on
the net. But as long as my browser does not mind, I am usually
fine with this.




 Currently, I am using this CSS stylesheet to display them:
 http://www.w3.org/StyleSheets/Core/stylebot.html?family=8&doc=Sampler


Nice. Although I am not even sure whether it is advisable
to use stylesheets in a documentation or not. In general
I think plain HTML (not plain text!) is good enough for
most docs and pages tend to load quicker.

But maybe I am just scared of these web pages which
cover 30% of my screen width with microscopic font
sizes - proudly produced by CSS enthusiasts.



 Walter has requested to use the Wiki4D for doc suggestions:
 http://www.prowiki.org/wiki4d/wiki.cgi?DocComments

 And I'll probably resend my converted docs to him, some day.
 Maybe I can get a free copy of DMD 1.0 in return ? :-)


D will be free until release 0.999, from 1.0 onwards you
can get a license for $2999.95, bulk licenses of 1000 or
more will be cheaper, the linker will cost extra ...
Apr 12 2005