PART II: Eiffel-View 1.1, the new Eiffel repository publishing tool
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:
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.