| |
 | Posted by Bob W |  Permalink Reply |
|
Bob W 
|
Walter has mentioned that he is planning to revamp the
D documentation and therefore warned me to put too much
effort in cleaning up existing HTML sources.
It actually takes me more effort to write these notes,
because the real work, cleaning up the HTML docs, is and
was repeatedly done by - can you guess? - a D program.
It is helping me to get the D docs into my preferred
format for offline viewing every time a new release is
coming up.
After some thoughts, I have decided to release the
relatively unpolished program to the general public.
This application can handle all the current doc files and
cleans them up a bit. This could still be useful for future
documentation plans, so you guys might want to take a
look at it.
Since the news server does not allow me to upload the modified files, I suggest you to do the following:
1) Unzip the attachment and compile the DmdHtml.d file. You'll need DMD on a Windows machine. "DmdHtml" does not cater for Linux yet, sorry.
2) Run "DmdHtml" from the command line without parameters to get some info if you're interested.
3) Copy the entire documentation directory you want to
convert to a new directory (you need all files to test
the result, not just the modified ones).
4) Run "DmdHtml.exe" from the command line and supply it
with the original and the newly copied directory names.
Make sure that you specify the -y option, otherwise
"DmdHtml" is not allowed to overwrite files in the
destination directory.
Example 1: DmdHtml html html_new -y
Example 2: DmdHtml html html_new -y >log.txt
5) Now you must copy "style.css" which you have found
in the zipped attachment to both the "d" and the
"d\phobos" directories.
6) Look for index.html in the "d" directory, open it
and be surprised: Same look, same feel, but less guilt
due to the improved HTML code. ;-)
7) You probably have noticed a file which is called
"dark_age_style.css" in the zipped attachment. This
features a radically altered color scheme and will most
likely not become mainstream D-documentation-look.
But it is a good example for the newly gained flexibility
of the altered HTML files. If you want to try this,
just change its name to "style.css" and copy it to the
new "d" and "d\phobos" directories.
Further info:
Changes to D documentation (V 0.133):
Please note that all changes I've made to the D HTML docs did never affect the contents of the pages. I have also done my best to prevent modifications resulting in layout changes.
Modifications performed to HTML and CSS files:
- All HTML files can now utilize the stylesheet "style.css"
Most phobos files did not have the required <link..> tag
in their HTML headers.
- All files which had <body..> parameters defined have
been changed for a plain <body> tag to ensure that
"style.css" can do its job.
- The column tag <TD..> which was defining the background
color for the left menu (toc), has been modified to use
class="toc". Parameters for toc were already defined in
the stylesheet but obviously never implemented.
- Some files contained <font color="#000066" face="mono">
after <pre> tags. This <font..> tag is useless because
<pre> is monospaced by default and its font colors are
already defined in "style.css".
- Unneeded and flawed tables around <pre> sections were
removed. This ensures uniform look of code samples and
the removal of some invalid HTML code
(e.g.: </td></pre></tr>).
- Some (but probably not all) of the <pre> sections which
are obviously containing D code have been changed from
<pre> to <pre class="dcode">.
- Both, the "d" and the "phobos" directory require their
own stylesheet, which is named "style.css" in both cases.
They were originally different, but I have supplied a
slightly updated version which is compatible with both
sets of files.
- Most HTML files had whitespace garbage at the end and
several blank lines at their beginning. I originally
wanted to keep the blank lines because they looked
intentional, but I have seen that a few files have
been recently (V 0.133) stripped of this blank section,
so I have compacted all of them accordingly.
- Special situation: the comparison table (D with other
languages) is not suitable for a modified color scheme.
Therefore its bgcolor parameters are replaced with
class parameters to allow quick color changes via
the stylesheet.
What has not been done:
- In "style.css" I have found entries which are obviously
not in use. I have just marked them for deletion, because
I did not want to do this without knowing the reason for
them being there.
- Two files are present which are being not linked to:
"blank.html" and "notimpl.html".
They are old and most likely outdated but nevertheless
were always supplied with all the most recent releases
of DmD. Even so, I have not deleted them but I suggest
doing that if they won't be needed in future.
- I guess none of the D doc files currently contains pure and
valid HTML 4.01 od XHTML. This situation has not changed
even after all my modifications. Since most browsers will
not have problems displaying the D doc contents correctly,
the workload involved to correct and validate all pages
would most likely be unjustified.
Why did I do this?
In order to reduce eyestrain I tend to change all my
offline documentation for inverted color display (dark
background). I have done this for most docs of the past
D releases too. During that process I have noticed that
several provisions in the stylesheets are lacking
corresponding implementations in the HTML files.
So I have decided to make several corrections to the
files in order to simplify the process of changing
colors by using modified stylesheets.
Optional future modifications (upon request):
- Phobos files can be modified to accept the stylesheet in
the "d" directory (1 level up). The benefit of this will
facilitate uniform display throughout the documentation
pages. Furthermore maintaining a single "style.css" will
be obviously simpler.
- I have noticed that most files are using Unix-style "LF"
characters instead of the "CR/LF" Windows format. One of
the WWW related RFC docs seems to favour the "CR/LF" format,
because it is less problematic on Unix systems than the "LF"
format is on Windows systems. Some of the D docs have a
mix of "LF" and "CR/LF" line separation. Therefore I suggest
to use "CR/LF" for all the docs (and generously accept an
estimated 3 percent size penalty).
- Javascript items could be removed for offline viewing if
most browsers nowadays prevent Javascript being run on
offline pages due to security constraints. The web version
will probably always depend on Javascript in order to get
D's Google ads to generate some revenue ...
|
