Part I: Eiffel-View 1.0, the new Eiffel repository publishing tool

by Finnian Reilly (modified: 2016 Jul 23)

Repository Publishing

If you have published your Eiffel code in a source repository like Github or Source Forge you will know that this is not the most ideal way to browse and explore Eiffel source code. There are a number of problems:

  1. Browsing in github requires endless drilling down into a deep directory structure and there is a noticeable delay for pages to load. What is preferable is a less granular view of the directory structure that will eliminate a lot of drilling down.
  2. If a class contains useful note documentation, you won't know about it's existence unless you actually open the class. Most times you will open the class and will discover there is no useful documentation. A wasted page load! What is need is a way to present any useful class notes on the same page as the link to the source code. If only some of the classes in a directory have useful notes, these should be listed first.
  3. Class notes are viewable only in source code form. If they contain any useful formatting information, there is no possibility to see it rendered in HTML.
  4. Once you open the source view, you will find that in github the indentation tabs are too large, so often the code does not fit nicely into the available browser space. Three spaces per tab is a much better default.
  5. If you want to see an example of how a library class is used, be prepared to spend a lot of time looking for an example.
  6. If you are only interested to read the code, the line number margin is a waste of space.

Introducing Eiffel-View

Eiffel-View is a new repository publishing tool that provides a solution to the code browsing problems identified in the introduction. However it does not manage the code, so you still need github or similar. It has been used to publish all the source code for the Eiffel-Loop repository which you can see here: www.eiffel-loop.com.

Part II to follow

This article is in two parts. In a follow up article I will be outlining some further improvements that could be made to make the tool more universally useful.

Features

Repository Statistics

A short summary of the repository contents is placed at the top of the home page. As for example:

Repository Statistics
1784 Eiffel classes containing 435288 words* of code. Total source code: 4.2 mb.
* Code words include keywords, identifier words and quoted strings, but exclude comments and indexing notes.

Dependency checking

A CRC-32 digest of each source code file is placed as a meta-tag of the corresponding html page. Eiffel-View is smart enough to work out the dependencies of every generated html page. Only pages that need rewriting are rewritten on subsequent runs.

Synchronization

Automatically synchronizes contents with the hosting site by ftp.

Note field markdown rendering

Eiffel-View renders as html markdown used in the class description field. The markdown used is similar to Github markdown but there are some differences.

All relative paths

All links to image files, style sheets etc, use relative paths. This means the website can be browsed locally in a directory folder.

Source Bookmarking Link

Each source code html page has a book mark link at the top. However it links to an anchor in the index page, not the source file itself.

Prism Syntax Highlighting

Eiffel-View makes use of the Prism js/css tool for syntax highlighting the Eiffel source code.

Client Example Links

Eiffel-View provides links to usage examples (maximum of 20) for any classes in the library folder. In Eiffel-Loop the usage examples are found in either the example, tool or test directories.For an example see class EL_MODULE_EVOLICITY_TEMPLATES

Configuration file

A configuration file allows you specify a list of named directories that will appear in the home page sitemap. This is a more granular approach then using ECF files to specify the repository contents.

doc-config/config.pyx

The file is written in Pyxis format. The ftp-site section is optional.

Eiffel-View Markdown Summary

Highlighted sections

Words quoted with a grave accent ( ) to open and an apostrophe (') to close are <code>highlighted'</code>. This follows an established Eiffel convention used in source comments for quoting routine names. See class EL_REMOTE_ROUTINE_CALL_REQUEST_HANDLER for an example.

Bold words

This is the same as Github markdown. Use two asterisk on either side of the **words you** want to make bold

Code blocks

Consecutive lines in the description which have an indent of 3 or more tabs are highlighted as a quoted code block with a fixed size font. See class EIFFEL_FEATURE_EDITOR_APP for an example.

Hyper links

Hyper links use the same convention as mediawiki-formatting as for example:[http://website.com See here]

Relative source links

There is a specialized link that allows you reference other source code files in a class description. You write the link as though you were referencing the other Eiffel source file and then you change the .e extension to .html. For example:note description: "[ See class [../../eiffel-dev/class-edit/support/feature_constants.html FEATURE_CONSTANTS]. ]"
See class EIFFEL_FEATURE_EDITOR_APP for an actual example.

Note that if you want to reference a class in the same directory you need to precede the page name with ./ as in this example for class EL_C_CALLABLE.

Tool Source Code

The source code for Eiffel-view can be viewed in directory eiffel-dev/library/publish.

Tool Download

A binary for the tool is available on Github as part of the 1.4.0 release of Eiffel-Loop:

el_toolkit-1.1.20

The build is for Linux Mint 17 which is based on Ubuntu 14.04. It might work on other versions of Ubuntu but I haven't tested.

Tool Usage

The following script found in the Eiffel-Loop root directory shows how to use the tool# File: build_doc.sh export EIFFEL_LOOP=$(pwd) export EIFFEL_LOOP_DOC=$EIFFEL_LOOP/doc read -p 'Enter a version number: ' version el_toolkit -publish_repository -config doc-config/config.pyx -version $version

Source View Template

The following is the Evolicity html template for the html source code pages. Evolicity is a text substitution language that can output Eiffel objects into text. It is part of Eiffel-Loop.<code lang="xml"> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="www.w3.org/1999/xhtml" lang="en"> $source_path <body>

class $name

#if $is_library then #if $client_examples.count > 0 then

Client examples: #across $client_examples as $example loop #if $example.cursor_index > 1 then ;  #end $example.item.name #end

#end #end
$code_text

  </body>

</html></code>

Main Template

The following is the main Evolicity html template is for eiffel-loop.com for all index pages and the home page sitemap.<code lang="xml"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en">

<head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
     <meta name="Author" content="Finnian Reilly"/>
     <meta name="Audience" content="all"/>
     <meta name="Content-Language" content="english">
  #if $is_index_page then
     <meta name="Description" content="Eiffel-Loop is a collection of tools and software 
                 components for Eiffel developers"/>
  #else
     <meta name="Description" content="Source code for Eiffel $category: $name"/>
  #end
     <meta name="Keywords" content="Eiffel language, Eiffel library, Eiffel programming, Eiffel developer
              , Eiffel coder, Eiffel code, Eiffel source code, Eiffel source, Eiffel open source"/>
     <meta name="ROBOTS" content="Index, FOLLOW">
     <title>$title</title>
     <style type="text/css">
        @import "$top_dir/css/default.css";
     </style>
  </head>
  <body>
  <a name="top"></a>
  <div id="centered">
     <a href="$top_dir/index.html" title="Eiffel-Loop Home"><img src="$top_dir/images/banner-logo.png"></a>
     <div id="download">
        <p><a href="$github_url" target="_blank">Github</a></p>
        <p>Download latest: <a href="$github_url/archive/${version}.zip">Windows</a> 
           or <a href="$github_url/archive/${version}.tar.gz">Linux</a>
        </p>
     </div>
     <div id="text">
  #if $is_index_page then
     <h2>Repository Statistics</h2>
     <p>
        <b>$stats.class_count</b> Eiffel classes containing <b>$stats.word_count</b> words of code*.
        Total source code: <b>$stats.mega_bytes mb</b>.
     </p>
     <p>
        <small>* Code words include keywords and identifier words but exclude comments and indexing notes.
        </small>
     </p>
     #across $category_list as $category loop
        <h2>$category.item.name</h2>
        #across $category.item.page_list as $page loop
        <p><a href="$page.item.relative_file_path">$page.item.name</a></p>
        #end
     #end
  #else
     <h1>$category: $name</h1>
     <h2>Directory: $relative_path</h2>
     #if $has_sub_directory then
        #across $directory_list as $directory loop
        <p><a href="#$directory.item.index">$directory.item.contents_dir_title</a></p>
        #end
     #end
     #across $directory_list as $directory loop
        #if $has_sub_directory then
     <h3><a name="$directory.item.index">$directory.item.dir_title</a></h3>
        #else
     <h3>Classes</h3>
        #end
        #across $directory.item.class_list as $class loop
     <h4><a href="$class.item.html_path" name="$class.item.name" target="_blank">$class.item.name</a></h4>
           #across $class.item.description_paragraphs as $paragraph loop
              #if $paragraph.item.is_preformatted then
     <pre>$paragraph.item.text</pre>
              #else
     <p>$paragraph.item.text</p>
              #end
           #end
           #if $class.item.is_library then
              #if $class.item.client_examples.count > 0 then
                 <h4>Client examples</h4>
                 <p><small>
                 #across $class.item.client_examples as $example loop
                    #if $example.cursor_index > 1 then
                       ; 
                    #end
                    <a href="$top_dir/$example.item.relative_dir/${example.item.name_as_lower}.html"
                       target="_blank">$example.item.name</a>
                 #end
                 </small></p>
              #end
           #end
        #end
     #end
  #end
     <br>
     </div>
     <div id="footer">
        <a href="#top" title="Scroll to top of page"><img src="$top_dir/images/top.png"></a>
        <p>Copyright © 2016 Finnian Reilly</p>
     </div>
  </div>
  </body>

</html></xml>

Comments
  • Alexander Kogtenkov (9 months ago 15/7/2016)

    Gray background

    Is there any reason to have gray background? (The text looks next to unreadable to me in this setting.)

    Also looking at random classes of Eiffel-loop libraries it turns out they do not provide much information how to use them, in particular because of missing class descriptions and empty feature comments.

    • Finnian Reilly (9 months ago 15/7/2016)

      Gray background

      Is there any reason to have gray background?

      Probably because I am old school. Back in the early days of the Internet in the 90's, the most popular web browser was called Netscape Navigator, and the default background color was, guess what.. gray.

      Screenshot

      I find that for long periods of reading that the high contrast of black on white hurts my eyes. I much prefer either gray (or pale green).

      • Alexander Kogtenkov (9 months ago 15/7/2016)

        Gray background

        For the same reason I'm dimming my display so that everything appears in reasonably low contrast. This works almost in all cases except this one. Hopefully this affects only me.

        • Finnian Reilly (9 months ago 15/7/2016)

          Browser preference

          One suggestion for you is to override the style sheet colors in your browser preferences with a background color of your own choosing. I don't think you can do this on Chrome but on Firefox it's about:preferences#content and in IE it's in the accessibility options.

    • Finnian Reilly (9 months ago 15/7/2016)

      Missing class descriptions

      Publishing my source on a website is the first step of a long term project to provide better documentation. Now that they can be rendered as HTML I have a bigger incentive to supply descriptions for classes and in fact I have already spent time adding them. I also have separately written documentation for many modules that I plan to integrate later.

      But if there are some classes you are particularly interested in, let me know and i will see what I can do