VHDLHandbook Toolchain

Design and VHDL handbook for VLSI development toolchain that convert XML to PDF.

Introduction

This toolchain converts xml rules to PDF files including images, VHDL examples and additionnal texts.

Dependencies

See wiki Dependencies section

Project structure

The project is structured as follows :

• build.xml is the Ant building script

• ant.properties defines various parameters for the building process

• A stylesheets folder containing XSLT stylesheets to transform the XML rulesets

• A src_handbook folder containing a directory for each ruleset seen as a submodule.

• A 'Text' folder including texts for introduction, glossary and some release info

• A 'Scripts' folder including the different Ant scripts called from the build.xml one

Building

You may first modify your ant.properties according to your development environment (changing path of Saxon and FOP) and put your handbook xml files (including an addtionnal xml to customize the revision of your pdf release) in the dedicated folder.

Project settings

Main parameters

Parameter	Description
project.list	List of the projects folder to take into account for creating the handbook file
file.handbookPDF_name	Final filename of the handbook file, without .pdf extension
file.subtitle_edition	Subtitle of PDF to indicate Standard Edition or Custom Edition Information
pdf.enable.sonarqube	Enable or disable the display of sonarqube section in pdf file (value = true or false)

Folders

Parameter	Description
folder.src	Source folder, containing scripts, rulesets, stylesheets and extras
folder.out	Output folder, containing PDF output and temporary files
folder.out.work	Work folder containing merged sources
folder.xsd	Folder containing XSD schemas
folder.partial.images	Folder containing the rules' illustrations (only this folder name)
folder.partial.vhdl	Folder containing VHDL examples (only this folder name)
folder.partial.ruleset	Folder containing the rulesets XML files (only this folder name)
folder.scripts	Scripts folder, containing all the Ant scripts called from build.xml
folder.home	Project folder
folder.vhdl	Folder containing VHDL examples
folder.text	Folder containing texts from introduction, glossary and release info
folder.images	Folder containing the rules' illustrations
folder.ruleset	Folder containing the rulesets XML files
folder.out.temp	Temporary folder, containing temporary files generated by scripts
folder.stylesheet	Stylesheets folder, containing all the XSLT scripts
docbook.xsl.dir	Folder containing the Docbook stylesheets
saxon.lib.dir	Folder containing Saxon
fop.home	Folder containing FOP

Configuration parameters

Parameter	Description
file.export_std_rules_pdf	Set to True to include Standard ruleset inside the generated PDF
file.export_custom_rules_pdf	Set to True to include Custom ruleset inside the generated PDF
VHDL.tag	Tag set to determine the part of the example to display from VHDL files

Input files

Parameter	Description
file.main_name	Input file name: a handbook header (contains one RuleSetHist for PDF release)
file.main_name_extension	Input file name: a handbook header (contains one RuleSetHist for PDF release)

Style sheets

Parameter	Description
file.xsl.merge	Style sheet used for merge the input xml files
file.xsl.sorting	Style sheet used for sorting
file.xsl.convert2docbook	Style sheet for conversion into docbook format
file.xsl.fopCustomization	Style sheet to customize fop parameters
docbook.xsl.dir	Folder for docbook
fo.stylesheet	Folder and main entry for docbook

Ant Build

If this is the first time you want to build the project, select build.xml, run as 2 Ant Build, and click on Run. Otherwise, just run as 1 Ant Build.

Handbook rules

The rules are described by a set of XML tags according to the handbook.xsd schema.

A rule has the following template :

<hb:Rule UID="LLL_DDD">
	<hb:RuleUID>LLL_DDDDD</hb:RuleUID>
	<hb:RuleHist>
		<hb:Status>Status</hb:Status>
		<hb:Version>X</hb:Version>
		<hb:Creation>YYYY-MM-DD</hb:Creation>
		<hb:Modified>YYYY-MM-DD</hb:Modified>
		<hb:Revision>
			V1 : YYYY-MM-DD : Creation
			V2 : YYYY-MM-DD : CatModified1 ; CatModified2
            		V3 : YYYY-MM-DD : CatModified3
        	</hb:Revision>
	</hb:RuleHist>
	<hb:RuleContent>
		<hb:Name>Rule name</hb:Name>
		<hb:IsParent>false</hb:IsParent>
		<hb:IsSon>false</hb:IsSon>
		<hb:ParentUID xsi:nil="true" />
		<hb:Technology>Technology</hb:Technology>
		<hb:ApplicationFields>ApplicationFields</hb:ApplicationFields>
		<hb:Category>Category</hb:Category>
		<hb:SubCategory>SubCategory</hb:SubCategory>
		<hb:Severity>Severity</hb:Severity>
		<hb:Rationale>Some rationale related to the rule.</hb:Rationale>
		<hb:ShortDesc>A Short description of the rule.</hb:ShortDesc>
		<hb:LongDesc>A longer description in which you can do some formatting that will be kept</hb:LongDesc>
	</hb:RuleContent>
	<hb:Sonarqube>
		<hb:SonarType>Type of problem</hb:SonarType>
		<hb:SonarSeverity>Problem severity</hb:SonarSeverity>
		<hb:RemediationEffort>Estimated effort for correction</hb:RemediationEffort>
		<hb:SonarTag>Tag</hb:SonarTag>
	</hb:Sonarqube>
	<hb:RuleDesc>
		<hb:GoodExDesc>A description of the good example (leave empty if none needed)</hb:GoodExDesc>
		<hb:GoodExample>GoodExampleFileName</hb:GoodExample>
		<hb:BadExDesc>A description of the bad example (leave empty if none needed)</hb:BadExDesc>
		<hb:BadExample>BadExampleFileName</hb:BadExample>
		<hb:FigureDesc>A description of the figure illustrating the rule</hb:FigureDesc>
		<hb:Figure>TheFileNameOfTheFigure</hb:Figure>
	</hb:RuleDesc>
	<!-- Optional element -->
	<hb:RuleParams>
		<!-- 0 or n elements of each following sections can be present --> 
		<hb:IntParam>
			<hb:ParamID>ParamID</hb:ParamID>
			<hb:Relation>Relation</hb:Relation>
			<hb:Value>IntegerValue</hb:Value>
		</hb:IntParam>
		<hb:StringParam>
			<hb:ParamID>ParamID</hb:ParamID>
			<hb:Position>Position</hb:Position>
			<hb:Value>String Value</hb:Value>
		</hb:StringParam>
		<hb:RangeParam>
			<hb:ParamID>ParamID</hb:ParamID>
			<hb:Range>Range</hb:Range>
			<hb:ValueMin>Integer min value</hb:ValueMin>
			<hb:ValueMax>Integer max value</hb:ValueMax>
		</hb:RangeParam>
	</hb:RuleParams>
	<!-- End of optional element-->
</hb:Rule>

The Sonarqube section is optional.

License

The handbook is published under the GNU GPLv3 license, available in the LICENSE file.