Eiffel-View Repository Publisher Version 1.3

by Finnian Reilly (modified: 2018 Oct 09)

    Contents
  1. Introduction
  2. Whats New?
    1. ECF-centric Configuration
    2. ECF Title and Descriptions
    3. Analogous URL Paths
    4. Expanded Source Links
      1. Link Checking
    5. Faster Performance
    6. New Support Tools
  3. Main Features
    1. Code Statistics
    2. Relative Hyperlinks
    3. Formatting
      1. Code Sections
      2. Unordered Lists
      3. Ordered Lists
      4. Italics
      5. Bold
    4. Github Contents.md
  4. Example Configuration
  5. Support Tools
    1. Class Link Checker
    2. Descendant Note Generator
    3. Blogging Class Link Expander
  6. Download
    1. Example Launch Script

Introduction

Version 1.3 of the Eiffel-View Repository Publisher sees some major new improvements. The publisher has been used to generate the Eiffel-Loop website as static content, but can be used to publish any Eiffel repository by changing the configuration files and HTML templates.

I have written previously about the publisher in these articles

  1. Eiffel-View 1.0
  2. Eiffel-View 1.1

Whats New?

ECF-centric Configuration

Previously the publisher did not make use of ECF files in the configuration, so there was some duplication of description text and cluster path information. Now the configuration only references ECF files, as for example:publish-repository: ecf-list: # Examples ecf: "example/net/EROS/server/eros-server.ecf" "example/net/EROS/test-clients/test-clients.ecf" "example/99-bottles/ninety-nine-bottles.ecf" "example/eiffel2java/eiffel2java.ecf" "example/manage-mp3/manage-mp3.ecf" "example/graphical/graphical.ecf" # Tools ecf: "tool/eiffel/eiffel.ecf" "tool/toolkit/toolkit.ecf"Isolating Clusters

But for ECF that contains very many source files, it is possible to assign a separate page to each cluster by referencing the cluster name in the configuration and optionally adding a short description.

For example:

# Splitting Eiffel-Loop/library/base/base.ecf by cluster publish-repository: ecf-list: # Library Base ecf: cluster = data_structure "library/base/base.ecf" ecf: cluster = math "library/base/base.ecf" ecf: cluster = persistency "library/base/base.ecf" description: """ Data Persistence Classes for reading and writing data to files """The URL of the ECF HTML page becomes qualified by the cluster name, as for example:

http://www.eiffel-loop.com/library/base/base.persistency.html

ECF Title and Descriptions

The names and descriptions for each library are obtained from the ECF as follows.

  1. The publisher looks for the XML node /system/description
  2. The first line of the description is taken to be the library title
  3. The remainder of the text is taken to be the description
  4. If the last line contains a reference to a text file, in the form See <path> for details, the contents of this text file are added to the description. This makes it convenient to edit a very long and detailed ECF description.
  5. Any wiki-style-markup is expanded in the generated HTML page. Note that the Eiffel-View markup differs from standard wiki-markup in a number of respects.

(ECF in Pyxis format)system: configuration_ns = "1-16-0" name = EL_eco_db; uuid = "229B73E4-09AA-11DF-87BB-93E5E9639079" library_target = EL_eco_db description: """ Eco-DB (Eiffel CHAIN Orientated Database) ''Eco-DB'' is an acronym for ''Eiffel CHAIN Orientated Database'', and enables the development of container objects conforming to the base class [https://www.eiffel.org/files/doc/static/18.01/libraries/base/chain_chart.html CHAIN] to have many of the properties of relational database tables. See doc/eco-db.txt for details """

Analogous URL Paths

Now the URL path for each ECF HTML page is analogous to the relative location in the source code repository. This makes it possible to included links to a github repository for the ECF files in the ECF HTML template:

Fragment of directory-tree-content.html.evol<h1>$category_title: $name</h1> #if not $description_elements.is_empty then <h3>Classes</h3> #if $has_ecf_name then <p><b>ECF:</b> <a href="$github_url/blob/master/$ecf_path" target="_blank" title="$ecf_name on github">$ecf_name</a></p> #end <p><a href="#class_listing">Directory source listing</a></p> <h3>Overview</h3> #else #if $has_ecf_name then <p><b>ECF:</b> <a href="$github_url/blob/master/$ecf_path" target="_blank" title="$ecf_name on github">$ecf_name</a></p> #end #end

Expanded Source Links

There is now a convenient way to automatically generate hyper-links to class source pages, using a special markup variable in either a class indexing field, or an ECF description. Take class EL_FACTORY_CLIENT for example:note description: "Allows descendants access to initialization agents for [$source EL_OBJECT_FACTORY]" author: "Finnian Reilly" copyright: "Copyright (c) 2001-2017 Finnian Reilly" contact: "finnian at eiffel hyphen loop dot com" license: "MIT license (See: en.wikipedia.org/wiki/MIT_License)" date: "2018-09-20 11:35:12 GMT (Thursday 20th September 2018)" revision: "4" class EL_FACTORY_CLIENT endThe variable $source is automatically expanded as a page-relative URL to the page:

library/base/data_structure/dynamic_creation/el_factory_client.html

Link Checking

As classes are constantly being renamed, there is a link checking tool to make sure there is a valid class name for every $source link. See below.

Faster Performance

With the introduction of concurrency, the publisher is now able to parse and index about 5 mb of code in under 15 secs on an 8 core Intel i7 processor. You can select the number of cores you wish to use in the main configuration file.

Incidentally, the concurrency code to do this is a nice illustration of class EL_PROCEDURE_DISTRIBUTER applied to the routine read_sources_files in the class EIFFEL_CONFIGURATION_FILE.

Thanks to a CRC checksum in each generated file, it does not have to needlessly regenerate HTML files each time. Only those files where the checksums differ from the corresponding Eiffel source.

<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> <head> <meta name="Description" content="Source code for Eiffel $category_title: $name"/> <meta name="digest" content="$crc_digest"/> ...Thanks to FTP synchronization, only those files which have been modified or removed need to be updated on the website.

New Support Tools

Three supporting/related tools for the publisher have been added. See the section Support Tools below.

Main Features

The following features are not new but worth repeating.

Code Statistics

The publisher is able to generate various repository statistics which can be referenced in the site index page with the following template code:

<p><b>Statistics:</b> Eiffel-Loop has <b>$stats.class_count</b> classes containing <b>$stats.word_count</b> words* of code. Total size: <b>$stats.mega_bytes mb</b>.</p>

Relative Hyperlinks

The repository does not use any absolute paths. All links are relative to the current page. This means the generated HTML will function just the same when viewed locally on the file system. This is useful for distributing documentation as an archive for download.

Formatting

Code Sections

There are two ways to highlight an area of text as source code material, which can be either just a single code expression, like a routine call or attribute name, or several lines of source code.

  1. Use the standard Eiffel convention of quoting code expressions with a grave accent ` to open and an apostrophe ' to close. For example `foo.bar' will be output in HTML as <em id="code">foo.bar</em>. Use CSS style-sheets to render this emphasis with a fixed width font and perhaps a different background color.
  2. Indent a number of lines by one tab stop relative to previous text. This will cause the lines to be output in HTML inside the preformatting element <pre>.

See class EL_REMOTE_ROUTINE_CALL_REQUEST_HANDLER for examples of both kinds of code formatting.

Unordered Lists

The markdown for bullet points is an asterisk at the start of a line followed by a space. Nested list are not supported.* Point one * Point two

Ordered Lists

The markdown for a numbered list is an natural number followed by a dot followed by a space. Nested lists are not supported.1. Point one 2. Point twoOrdered list items are rendered with HTML as follows:<li><span>Item text</span></li>This allows the possibility of using CSS to make the numbers bold while keeping the item texts normal.ol { font-weight: bold; } li span { font-weight: normal; }

Italics

Double single quotes on either side of a ''word''.

Bold

Double asterisks on either side of a **word**.

Github Contents.md

Eiffel-view will automatically generate the contents of the site-map page translated into Github markdown. The file is named Contents.md and is output into the publisher output root directory.

For example: doc/Contents.md

This Contents.md file can be referenced from the Readme.md in the github repository root.

Example Configuration

The templates and publisher configuration files for the Eiffel-Loop website can be view on github here:

Eiffel-Loop/tree/master/doc-config

Note: I have noticed some binary files with extension *.evc, which are not supposed to be there. Please ignore those.

Support Tools

Also are in the el_eiffel are two related sub-application tools that support the repository publisher. Two of these tools use the same configuration file that you use to publish repositories.

Class Link Checker

The following command switch will check all the class names used in $source links for invalid names:

el_eiffel -check_note_links -config doc-config/config.pyx -threads <number> -ask_user_to_quit

Descendant Note Generator

The following tool can be integrated with EiffelStudio as an external tool with the commandel_eiffel -descendants -no_highlighting -out_dir doc/descendant -class $class_nameThis will output a descendant tree with added hyperlink markup for the currently selected class in the specified output directory. The tree will be formatted as Eiffel indexing note so you can add it to the end of a class as part of the documentation.

For example:note descendants: "See end of class" descendants: "[ EL_CRC_32_SYNC_ITEM* [$source EL_HTML_FILE_SYNC_ITEM]* [$source EIFFEL_CLASS] [$source LIBRARY_CLASS] [$source REPOSITORY_HTML_PAGE]* [$source EIFFEL_CONFIGURATION_INDEX_PAGE] [$source REPOSITORY_SITEMAP_PAGE] ]"Click on this link to see how this appears in the source HTML page:

library/base/runtime/file/transfer-sync/el_crc_32_sync_item.html

Blogging Class Link Expander

If you are writing an article on eiffel.org and you want to include a lot of links to class source pages in your repository website, then you can use this tool to expand the $source link variable and also to expand tabs with 3 spaces. The output is in a separate file with extension .expanded.txt

expand_eiffel-loop_links.sh#!/usr/bin/env bash export EIFFEL_LOOP=$EIFFEL/library/Eiffel-Loop export EIFFEL_LOOP_DOC=eiffel-loop.com #read -p 'Enter a version number: ' version el_eiffel -expand_links -config $EIFFEL_LOOP/doc-config/config.pyx $* read -p 'Press <return> to finish' reponse

If you are using the Nemo file manager you can use the following desktop entry to allow drag and drop of blog texts to invoke the expansion tool.[Desktop Entry] Comment= Terminal=false Name=Expand links Exec=gnome-terminal --command="expand_eiffel-loop_links.sh -version 1.4.8 -threads 8 -in '%f'" --geometry 140x50+100+100 --title="Expand wiki-markup source code links" Type=Application Icon=/home/finnian/dev/Eiffel/library/Eiffel-Loop/doc/images/logo.png

Download

A build for Ubuntu 14.04 can be downloaded here:

http://www.hex11software.com/resources/el_eiffel

Those who would like a Windows build will need to clone Eiffel-Loop and build tool/eiffel.ecf. There is a good chance the publisher will work on Windows, but I have not tested it.

Example Launch Script

#!/usr/bin/env bash export EIFFEL_LOOP=$EIFFEL/library/Eiffel-Loop export EIFFEL_LOOP_DOC=eiffel-loop.com #read -p 'Enter a version number: ' version # $* includes: -version <version number> el_eiffel -publish_repository -config eiffel-loop.com/config/config.pyx $* cp eiffel-loop.com/Contents.md $EIFFEL_LOOP/doc echo Copied Contents.md Eiffel-Loop/doc read -p 'Press <return> to finish' response