general.hpp File Reference

General plans regarding the html-services. More...

Go to the source code of this file.

Detailed Description

General plans regarding the html-services.

Link checking
  • A tool is needed which can follow all links and checks, for the local home page and for the Internet home page, whether they all work (returning the list of dysfunctional links).
General rules for html-pages
  1. We concentrate first solely on the content, presented in a simple and clear way.
  2. Indentation style:
    1. The standard xemacs indentation style doesn't work well; perhaps it doesn't understand xhtml?
    2. Setting the indentation step to 1 (instead of 2, the default) helps to reduce the amount of indentation.
    3. However, how to configure xemacs so that this is the default??
    4. When in html-mode, xemacs has a menu-entry HTML -> File Options -> Indent Step, which by default is 2, and which should be set to 1.
    5. One can demand to store the settings into a file, however, this stores in the html-file --- which is unacceptable.
    6. The variable settings seem to be
      (setq sgml-indent-data t)
      (setq sgml-indent-step 1)
      however putting this into custom.el doesn't make any difference?
  3. Presentation issues are only considered after the pages have been used for a while, and the system stabilised.
  4. These two basic rules are reflected by the technical requirements, that strict XHTML is used (thus deprecated features cannot be used, that is, representational issues are suppressed), and that appearance is handled via external style sheets, but only at a later point, after the development has settled.
  5. In general we want to leave as much details as possible to the browser, so that it can adapt the appearance to the users wishes. We are not an enterprise which needs to catch attraction by penetrating effects.
Install configuration system
  • We need documentation on this system for handling paths in html-documents.
  • Update all usages of absolute paths to our own html-pages or to doxygen-pages.
  • The m4-preprocessing should move to the Configuration-module.
  • Files created by the preprocessor should have a final line stating this and the creation date; then also (for easy of modification) the original template file should be specified (in a comment, or on the page). The local home page has already a first solution, which should be systematised, that is, a make-variable should be provided. Perhaps we just add "from ...", and state the original template file also on the page; the new make-variable then just contains the text with date etc.:
    automatic_masthead = Automatically created by the OKbuildsystem on $(current_date) from \
      template file "
    where then the template file has to be added (by hand). One problem here is that the current date should be the time when the specific page was created, not when the whole process started --- is this achieved by recursive make variables??
  • DONE (introduced makevariable extsrc_relative, which if non-empty activates relative paths to external-sources-documentation) Also all links to ExternalSources-docs need to be relativised, since otherwise apache doesn't understand the url's.
    1. We need to check, whether this works with ext-sources-doc and sys-dir-doc set to their target locations.
    2. However, then actually for normal use the documentation is not movable, since normally the documentation is placed in ExternalSources/doc, not in system_directories/doc.
    3. So better for external-sources-links we have the choice between absolute and relative paths, via a make-variable; default is absolute, while for creating the internet-html-directory it is switched to relative.
  • DONE Local url's should be relative (so that the html-documentation is movable): The preprocessing approach needs to be generalised:
    1. DONE (we simply precompute all relative paths; otherwise the algorithm is implemented as described) Best seems to create a function called by the m4-preprocessor (perhaps called "m4_RELPATH(C,T)"), which takes the current location C and the target location T, all as absolute paths, and creates from that the relative path from C to T:
      1. The algorithm is, that the longest common prefix (path) P of C and T is determined, and then the relative path from C to T goes first (size(C) - size(P))-many steps up, and then uses the piece of T starting with the end of P.
      2. Here I used paths as sequences in the C++ sense, and it seems best to implement this task as a little C++ application (there appears to be no existing tool for that purpose).
      3. Since all path names are constructed by us, we take their representation (as strings) literal, that is, do not use the equivalence of paths, but their equality (in terms of the Boost filesystem library, part of the standard in the future).
      4. A generic algorithm determines the longest prefix of two sequences (given by input iterators).
    2. The problem is how to get the current location?
    3. For html-files created by us we know their location (that is, where they will be put after preprocessing. Since we actually have make-variables (in the configuration system) for this, here we shouldn't have a problem.
    4. But what about files created by doxygen? As we do it now, we need a make-variable (in the configuration system) with the absolute address (to be manually read-off), which should also be alright.
    5. So all make-variables with url's contain absolute paths, while all created html-files (our's or by doxygen) contain relative paths.
    6. There are two types of html-files, our own and doxygen-created, and accordingly four types of links:
      • From our own files to other own files or to doxygen files we use the system with the make-variables as discussed above.
      • From doxygen-files to other doxygen-files we use the doxygen ability to handle parts of path names.
      • From doxygen-files to own files, there is the doxygen-capability of creating links via the "\link" command, but this seems to require a hard-coded path. Thus also here we use the above mechanism, together with the tag-construction, which creates the html-link-tag: Problematic, that only variable values can be used (no computations) ? Thus likely we have to compute these paths in advance, and store them in (make-)variables.
    7. DONE (created Configuration/Html/relative_paths.mak) It would be easiest if all relative addresses would be computed in advance in stored in make-configuration variables. Then better we create (in Configuration/Html) a specific makefile with all these settings, and this configuration makefile is only included by OKlibBuilding/Targets/html/Makefile.
  • See solution to "Configuration problem" below. DONE (the general usage is clear)
Search engines
  • See "Meta tags" in Buildsystem/Html/Local/plans/general.hpp.
  • The question is about whether search engines should be allowed to index the documentation.
  • We need to distinguish between external documentation and OKlib-documentation, and between the main OKlibrary-website and websites of users.
  • Perhaps the index pages for external documentation (e.g., documentation for Maxima or Boost) should be blocked, so that they are not indexed by search engines.
  • This is requested by the Gecode project (to avoid that a web search will lead to stale documentation).
  • The other web-pages (doxygen-created and "handmade") should invite search machines at the OKlibrary-website, but perhaps for the same reason they should block search engines at a user's site.
  • So index pages for external sources should obtain their "negative" meta-tags.
  • And our handmade html-pages as well as the doxygen-pages should obtain the meta-tages in the form of an m4-macro, which turns them on or off.
  • More precisely, turning on happens by
    <meta name="robot" content="all" />
    <meta "keywords" content="XXX, YYY" />
    while turning off apparently happens perhaps by
    <meta name="robot" content="none" />
  • For the doxygen-created pages we need to find an appropriate doxyygen-template (for the preamble of all created pages).
Handling of paths
  • The current system is rather complex.
  • We should seek to simplify it.
Creating styles
  • Carefully, basic style-sheets are introduced.
  • The information at the bottom (last change date, and page-author) should perhaps be one line, left-aligned the date, right-aligned the author.

Definition in file general.hpp.