V3 Publishing ANT Refactor

From HL7Wiki
Jump to: navigation, search

V3 Publishing ANT Script Refactoring

This is the proposed project page for the refactoring of the V3 Publishing Ant Scripts.

Purpose

The Project will restructure and clean up the ANT scripts that produce the Version 3 ballots. The ANT scripts will be reorganized to segregate the individual target into functionally related smaller files. The initial proposal is to create a file with domain targets, a file with DAM targets, a file with infrastructure targets, a file for installation targets, a files for core functions and some other non-specified (and as needed, discussed and approved) files. As the restructuring continues, additional opportunities to provide utilities to control the verbosity of the build and to segregate key external dependencies will also be explored.

PSS: File:Publishing-Refactor-PSS.docx

Design

Coding Guidelines

The refactoring will enforce the following coding guidelines on the ANT scripts:

  • Everything is indented, indent is 4 spaces
  • The content of a tag should be readable without side scrolling (generally no more than 120 columns), move attributes to the next line if there are too many or their size gets too wide.
    • Example:

           <xslt in="somewhere/else/to/look"
                 out="not/the/original/spot"
                 style="the/thing/that/does/the/work.xsl">
           </xslt>

  • All directory specifications use Unix directory separators: '/' not '\'
  • There is a blank line or a comment prior to each <target> with the exception that Eclipse style major/minor target comments should immediately precede the target

            <!-- ================================= 
                    target: Really-Important
                   ================================= -->
            <target name="Really-Important" description="The Big Thing" depends="minor, utility"/>
            
            <!-- - - - - - - - - - - - - - - - - - 
                    target: minor              
                   - - - - - - - - - - - - - - - - - -->
            <target name="minor" description="less important"/>
            
            <target name="utility" description="details stuff"/>

  • There are no blank lines in the body of a target (with one exception, see next item)
  • If a target has a description element, there can be a blank line after the description (this separates the description from the body of the target)

             <target name="-processThumbnails" if="useThumbnailProcessor">
   	          <description>Process thumbnails in directory 'graphicsDir' if useThumbnailProcessor is true</description>
                 
                  <echo> Process Thumbnails for directory ${graphicsDir} </echo>
              </target>

  • There are no double blank lines.
  • There is only one element (<something>) per line except when <not> wraps another element

              <if>
                   <not><available property="basis.coremifs.exist" file="${dir.input.support.basisfiles.coremifs}" type="dir"/></not>					
                   <then>
                       <antcall target="UpdateCoreResources"/>
                   </then>
               </if>

  • Comments never exceed 100 columns (the column needs to wrap)
  • If an attribute (thing="yada, yada, ....") exceeds 120 columns, it should be on a line by itself

Target Naming

  • When creating multiple targets for releases use the r.n notation. For instance itsxml_structures_1.1

Use Cases

The Publishing build has a number of major use cases to support and this should form the basis of the files organization. The use cases are:

  1. Initial installation and configuration of publishing tools
  2. Running the publication generation for domain content by publishing facilitators
  3. Running the publication generation for stand-alone (mainly infrastructure) content
  4. Running the publication generation for DAMS by publishing facilitator
  5. Packaging the content for submission by the publishing facilitator to the director of technical publications
  6. Generating the ballot by the director of technical publications
  7. Generating the normative edition by the director of technical publications

Build File Layout

Current Layout

The current build is comprised of the following files:

build-combined.xml
Contains

Test Execution Description

Iterations

  1. Make all directories use Unix directory styles
  2. Do even more cool stuff

Copyright © Health Level Seven International ® ALL RIGHTS RESERVED. The reproduction of this material in any form is strictly forbidden without the written permission of the publisher.