www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - V 0.133 HTML Docs Upload

reply "Bob W" <nospam aol.com> writes:
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 ...
Sep 27 2005
parent reply solotony <solotony sohu.com> writes:
I noticed dmdhtml did not solute directory, which is not exist.

BTW, phobos has a separate style.css

I suggest using the outer one by  import statement.

====phobos/style.css here==========================
 import url("../style.css");
====end here ======================================
Sep 30 2005
parent reply "Bob W" <nospam aol.com> writes:
"solotony" <solotony sohu.com> wrote in message 
news:Xns96E1DF2617C1DsolotonyATsohuDOTcom 63.105.9.61...

I noticed dmdhtml did not solute directory, which is not exist.

Not sure what the term 'solute' is supposed to mean but if you suggest that DmdHtml does not create directories, you are perfectly right. Therefore I have posted instructions how to use it. This program was never meant to be used by anyone besides myself, but I have decided to upload it instead of the already modified files which were too big for the new server. It (and its results) can be used as a reference by anyone interested, but that's about it. DmdHtml does a gentle cleaning of existing HTML documentation, but it does not solve the majority of problems. It is probably risk-free to use because it targets only known problematic sequences in the files without breaking anything. Walter could have used it for the 0.134 release but I guess he deemed that the benefits would not outweigh eventual risks involved. The question is did he mistrust my programming skills or his dmd compiler being still alpha stage ???? :-)
 BTW, phobos has a separate style.css

 I suggest using the outer one by  import statement.

 ====phobos/style.css here================
  import url("../style.css");
 ====end here ========================

Excellent idea, but I am not the one to decide. Maybe Walter will follow your suggestion. Alternatively he could update the <ink ..> tags of the files in the phobos directory instead of using two sets of stylesheets. The new one I have supplied is anyway meant to work with files in both directories.
Sep 30 2005
parent reply "Walter Bright" <newshound digitalmars.com> writes:
"Bob W" <nospam aol.com> wrote in message
news:dhkenf$306b$1 digitaldaemon.com...
 Excellent idea, but I am not the one to decide.
 Maybe Walter will follow your suggestion.
 Alternatively he could update the <ink ..> tags of
 the files in the phobos directory instead of using
 two sets of stylesheets. The new one I have supplied
 is anyway meant to work with files in both directories.

The only reason two style sheets are used instead of one is pure sloth on my part.
Sep 30 2005
parent "Bob W" <nospam aol.com> writes:
"Walter Bright" <newshound digitalmars.com> wrote in message 
news:dhl46i$1onl$1 digitaldaemon.com...
 The only reason two style sheets are used instead of one is pure sloth on 
 my
 part.

I perfectly understand. ;-) But here is the solution based on solotony's recommendation: - move the latest "style.css" (probably the one in phobos) to the "d" directory. - rename it to something like "marsstyle.css" - keep in all subdirectories a "style.css" consisting of only one line. For d/phobos file contents should be: import url("../marssstyle.css"); fir the d directory you want to use: import url("marssstyle.css"); Benefits: You can move directories and files and you have just to keep and maintain one valid copy of the "marsstyle.css". Instead of editing every <link> tag in those HTML files which are to be moved to a different location, you just keep your "style.css" files in all current and future subdirectories pointing to the proper location of "marsstyle.css".
Oct 01 2005