PART II: Eiffel-View 1.1, the new Eiffel repository publishing tool

by Finnian Reilly (modified: 2018 Oct 05)

Introduction

This is a follow up article to the introduction of Eiffel-View 1.0, a tool for publishing Eiffel repositories on a website. It offers a superior browsing experience to either Github or Sourceforge.

Version 1.1 has now been tried and tested on the Eiffel-Loop website. This article will explain the new features in ver. 1.1 with reference to eiffel-loop.com as an example.

Site-map Contents

The site-map home page now has a hyperlinked contents of the major repository repository sections.

Compacted Configuration

Configuration file format has been changed where possible to use element attributes in preference to text elements. See example Eiffel-Loop/doc-config/config.pyx. The basic configuration is only 15 lines.

Source Tree Descriptions

It is now possible to add descriptions for each source tree that will appear in the site-map home page. Eiffel-View markdown formatting can use for formatting the text. The descriptions are specified in the publishing configuration file. As for example: tree: name = "Interface to Matlab"; dir = "library/language_interface/Matlab" description: """ [http://uk.mathworks.com/products/matlab/ Matlab] is a popular math orientated scripting language. This interface was developed with Matlab Version 6.5, VC++ 8.0 Express Edition and Windows XP SP2. **(No longer maintained)** """ Python coders will recognize the triple-quote multi-line string manifest syntax. There is of course nothing wrong with the Eiffel syntax, but the Pyxis format was designed for a wider audience than the Eiffel community.

Longer Descriptions

Longer descriptions can be specified in a separate file with a .emd extension and referenced in the config file like this: # Library XML tree: name = "XML and Pyxis Document Scanning and Object Building (eXpat)"; dir = "library/persistency/xml/xdoc-scanning" description: "xdoc-scanning.emd" The .emd file is placed in the same directory as the config file.

The description field can be omitted altogether if the name of the .emd file matches the last step of the dir path as in this case.

Abbreviated Directory Contents

Version 1.1 allows you to keep the amount of text in the directory contents to a minimum. Only the description is listed after the class name, and for extended descriptions, the developer is encouraged to split into several note fields which will then appear in the source code page. Also for library directories the list of client examples now only appears in the source page.

Further Information Cue

If a class source page contains other information besides the description, the reader is made aware of this in the directory contents page by the inclusion of a header Further Information which provides a list of other note fields and the existence of a client example listing. For example: FEATURE_EDITOR_APP

Note Field Parsing

Version 1.1 has better note field parsing support.

Selected Fields

Version 1.0 could only read the description note field from the Eiffel source. But now it is possible to specify a list of note field names in the configuration file, and the entire Eiffel source code will be scanned looking for these fields. As for example: publish-repository: name = "Eiffel-Loop" include-notes: note: "description" "instructions" "notes" However only the description field will appear in the source tree contents page. The other fields will be rendered as html in the source code pages. Take a look at class EIFFEL_FEATURE_EDITOR_APP as an example.

Legacy String Syntax Support

Eiffel-Viewer can now parse the split-line string syntax found in many ISE classes, as for example: note description: "Objects that process `text' to include extra hidden characters % %at the Windows level." deferred class EV_INTERNALLY_PROCESSED_TEXTABLE_IMP

Enhanced Source Pages

In version 1.1 source pages now have the description and selected notes rendered in html. There is also a handy link at the top of the page with will skip all the notes and show the start of the class definition source code. Take a look at class FEATURE_EDITOR_APP as an example.

The very first link in the page, is a way to bookmark the class where it appears in the source contents page.

Eiffel-View Markdown

Eiffel-View now has support for both ordered and unordered lists

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 two Ordered 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.

For example: doc/Contents.md

The file is named Contents.md and is output into the publisher output root directory. This Contents.md file can be put into the github repository root and referenced in the Readme.md.

Download

Download the latest version of el_toolkit for Ubuntu 14.04 or Linux Mint 17.x here.