|
|
| (3 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| | + | __NOTOC__ |
| | + | [[Category:HowTo]] |
| | =Desktop Publication= | | =Desktop Publication= |
| − | Desktop Publication is a capability whereby '''''Publishing Facilitators''''' for particular domains or projects can manage their content, validate the completeness of that content, evaluate it for quality assurance issues, package it for submission as ballot content, and '''most importantly''' create a local replica of what their content will look like when included in a ballot.
| + | The entire previous content of this page has been removed, as the tools it documented have been withdrawn in favor of a new V3 Publishing Tool Suite that can be [http://gforge.hl7.org/gf/project/xmlpublishing/frs/ downloaded from Gforge] The new suite is documented under[[V3_Publishing_Process_Steps]], whose is also included below. |
| | | | |
| − | This capability reflects a combination of processes from various tools operating in a controlled file environment, and using ANT driven scripts to invoke sub-processes supported by those tools. The tools involved include:
| + | {{:V3_Publishing_Process_Steps}} |
| − | #'''''Publishing Processes''''' - the set of ANT scripts and transforms used at HL7 Head Quarters (HQ) to produce and test each V3 ballot site.
| |
| − | #'''''V3 Generator''''' - the set of ANT scripts and transforms used by HL7 HQ and others to convert the output files from the PubDb and Static Model Designer (see below) into MIF2 representation files; complete message and interaction schemas; html "table views" of each static model; and an Excel view of each static model.
| |
| − | #'''''PubDb''''' The Set of VBA code, table and form definitions that allows use of an Access data base to define and manage individual domains according to the constraints expressed in the HL7 methodology.
| |
| − | #'''''HL7 RMIM Designer (in Visio)''''' a combination of Visio stencils and detailed VBA code that supports "drag-and-drop" static model design while simultaneously invoking the constraints and content rules expressed in both the Hl7 Methodology, and the RIM and Vocabulary specifications.
| |
| − | #'''''RoseTree''''' - which supports the RMIM Designer (in Visio), HL7 PubDb, and vocabulary MIF assembly by providing automated access to the HL7 design repository (holds RIM and Vocabulary content) and command line processes that allow ANT scripts to invoke processes in the RMIM Designer and PubDB.
| |
| − | #Additional ANT scripts and transforms to support the integration of these tools, and the definition and execution of manifest generation, submission packaging, and quality assurance testing.
| |
| − | | |
| − | =Rudimentary Instructions for Complete “Desktop” Publishing=
| |
| − | ==System Dependencies & Installation==
| |
| − | #'''Dependency Note:''' These functions work equally well with Windows XP or Vista and Visio 2002 or Visio 2003-2007. There are no longer OS-specific BAT files. ANT automatically detects the OS and sets the directories accordingly.
| |
| − | #'''Limit:''' either Visio 2002 or Visio 2003-7 with either operating system, but extensive testing has only occurred for Visio 2002 on XP and Visio 2003-7 on Windows XP. Further, I do not know if Visio 2002 will even run on Vista. (woody@beelers.com)
| |
| − | #'''Configuration-specific BAT files''' have been created to deal with the Visio release differences, where necessary. In these cases, the BAT file names include either “Visio2002” or “Visio2003-7” in their names.
| |
| − | ==Installation==
| |
| − | #'''unzip hl7_v3pubgencombinedtools-*.zip''' archive into any available directory (ultimately requires about 800Mb MB)
| |
| − | #'''convert hidden batch files''' to functional batch files by changing the file "'''''1st_MAKE_THIS_FILE_dot_bat_and_RUN_it'''''" to a batch file, and running it (this changes all of the "*.rename_as_dot_bat" files to BAT files)
| |
| − | ==Adding domain content to directories and BAT files==
| |
| − | #'''Populate tool with your domain data'''
| |
| − | ##'''''convert the "generic" domain''''' (under input/domains) to the appropriate domain for your application (for example" uvrr")
| |
| − | ##'''''modify the file "generic-PublishLogged.bat"''''' by replacing the word "generic" with the abbreviation for your domain (such as uvrr) in the body of the file, and make the same substitution in the name of the file if desired.
| |
| − | ##'''''copy and repeat the above two steps''''' if you wish to process additional domains.
| |
| − | ##'''''add your "PubDB" and "design repository"''''' (if static model designs are being reported in a design repository) in the "databases" subdirectory of your domain
| |
| − | ##'''''add your Visio design files (*.vsd)''''' into the "sourcegraphics" subdirectory for all of your static model designs
| |
| − | ##'''''add your Visio "XML" files''''' for your static model designs to the "sourcegraphics" subdirectory for those static model designs are not recorded in a design repository, Delete the Visio “XML” files for designs that are recoded in a design repository.
| |
| − | ##'''''add your RoseTree "hmd" files''''' for your static model designs to the "sourcegraphics" subdirectory if your static model designs are\ recorded in a design repository,
| |
| − | ##'''''add your graphic files''''' for other content (storyboard interaction diagrams, local graphics, etc.) (in GIF, JPG, or PNG formats) in the "outputgraphics" subdirectory
| |
| − | ##'''''add other material to be referenced''''' in the domain (such as Adobe PDF files, or spreadsheets) to the "otherdistribution" subdirectory
| |
| − | #'''Reduce CMET source content''' to desired – If you wish to reduce the CMET coverage to a known, required sub-set of the total CMETs, follow this step
| |
| − | ##'''''edit input/support/ant/cmetSourceRetentions.txt''''' to create patterns that match the CMETs you wish to retain. All others will be deleted.
| |
| − | ##'''''run DeleteAllButSelectedCmetSource''''' and “press any key to continue” when prompted
| |
| − | #'''Publish the RIM, Datatypes and Vocabulary content''' to act as reference targets for your designs (this step only needs to be performed once)
| |
| − | ##'''''run RimDatatypesVocabulary-PublishLogged.bat'''''
| |
| − | ==General Processing Steps==
| |
| − | #'''Create "clickable" graphics''' for the domain static model designs (perform this step again any time graphic representation or content of static model is changed in the Visio in the "vsd")
| |
| − | ##'''''run CreateClickableGraphicsFromVsd-Visio2002.bat''''' or '''''CreateClickableGraphicsFromVsd-Visio2003-7.bat''''' (depending upon your Visio release)
| |
| − | #'''Extract the domain XML (dynamic model) file''' from the pub DB (this step will also be performed at the end to finalize the publication) (Todo: Change this to a be a file "synchronization" step and do not require it to completely publish the domain.)
| |
| − | ##'''''run <yourDomain>-PublishLogged.bat'''''. This will place Visio XML or design repository HMD files in the generator (Todo: Change ANT script to make this only move files for the selected domain, and provide another script that does the support files.)
| |
| − | ##'''''(not yet supported)''''' extract design repository HMD files and move them to the generator
| |
| − | Domain content: Generate Schemas, Table Views, Excel Views
| |
| − | #'''Run the generator''' to create table views, Excel views, and schemas for your designs (perform this step any time the static models are changed)
| |
| − | ##'''''run runlogged.bat''''' (generator takes 5-20 min or so)
| |
| − | ##'''''use Excel spreadsheet widget to convert CSV files to XLS''''' files this manual process requires file input/support/xsl/ HL7_RMIM_HMD_master-v2.26.xls
| |
| − | | |
| − | ==Domain Content Porcessing and Management==
| |
| − | ===Domain content: Publish/assemble domain HTML===
| |
| − | #'''Publish your domain content''' repeat this step whenever any of your content (particularly the PubDb) has been changed
| |
| − | ##'''''run <yourDomain>-PublishLoggedXP.bat''''' or '''''<yourDomain>-PublishLoggedVista.bat''''' (depending upon your OS)
| |
| − | ===Domain content: Manifest, Packaging and Quality Assurance===
| |
| − | #'''Dependency''' - As currently defined, this functionality is dependent upon the Generator source files having been populated. This is done by doing the initial set-up and "General Processing Steps" (above), although it does not require that clicakable graphics be created.
| |
| − | #'''Set "MessageReferences" source''' - This is the source file for the packaging and QA tests. This process will analyze both your domain "dynamic model"(the output from your PubDb) and your static models as defined in "Visio xml" and "RoseTree hmd" files. The manifest and packaging draw all of their information from the "dynamic model" (PubDb xml output), whereas the QA analysis uses both.
| |
| − | #'''''Run "PreviewReferenceErrors.bat"''''' file. This is a Generator process that runs at the beginning of every Generator run. Thus it deos not need to be re-executed, but, on the other hand, it is a quick (less than one minute process.
| |
| − | #'''Generate Manifest, ZIP and QA document''' - At this writing, this is a single process, because the process is quick and it did not seem valuable to segregate the steps. To execute this process, you will need to create a batch file with a single line: <br/>
| |
| − | '''BuildDomainManifestZip.bat uv''xx'''''<br/>
| |
| − | Where "xx" is replaced with the lower-case, two-character identifier for your domain. This file might be saved as "'''''BuildManifestZip-uvrr.bat'''''", for example.<br/><br/>
| |
| − | ##'''''"run the BAT file created above"'''''. When you do this, the following will be created:
| |
| − | ###'''manifests.xml''' is created in "'''''OutputFiles/Reports'''''". This is the source file for all the domains represented in the Generator. It is of little direct use to the domain Facilitator.
| |
| − | ###'''manifestSummary-uv''xx''.htm''' is created in "'''''input/domains/uv''xx'''". This file has a root element of "'''''manifest'''''" (no surprise there) with a name attribute that is the domain name (like "'''''uv''xx'''''"). The manifest contains a set of "'''''file'''''" elements that represent the individual lines of the manifest definition file (below). It also holds a set of "'''''reference'''''" elements that are of one of two types: "'''''spec'''''" and "'''''url'''''". The former are references using the "specRef" element to link to another specification in the HL7 Ballot, or a hyperlink to an HL7 or external web site. These should be reviewed to be certain they are current and that the links continue to work.
| |
| − | ###'''manifest-uv''xx''.txt''' is created in "'''''input/domains/uvxx'''''". This file is used by ANT to describe a "file set" of the files for including in the ZIP file. It will also be packaged as part of the ZIP file, and thus can be used by processes at HQ to manage the content or seek to recover it from SVN. (Todo: Make this happen.)
| |
| − | ###'''publishingPackage-uv''xx''.zip''' is created in the "'''''root'''''" directory of the tools (as a sibling to "'''''input'''''", "'''''ToolFiles'''''", etc.) It is the complete package of files from this domain to be sent to HQ. The ZIP file preserves the directory structure of the "'''''input/domains'''''" branches from which the content is drawn. This is the package that should be submitted to HQ for inclusion in the ballot. <br/><br/>
| |
| − | It should include all necessary files as:<br/>
| |
| − | ###*"'''''PubDb xml extract''''' from which the manifest was defined,
| |
| − | ###*"'''''Visio vsd'''''", and "'''''Visio xml'''''" or "'''''RoseTree hmd'''''" files for each static model defined in thePubDb. Note: It does not include the DMIMs.
| |
| − | ###*All "'''''graphic'''''" files referenced by the PubDb content, as picked up from "'''''outputgraphics'''''"
| |
| − | ###*All "'''''other'''''" files, like Word documents or Excel files or PDF documents that are picked up from "'''''otherdistribution'''''".
| |
| − | ###*'''''uv''xx''-qareview.htm''''' is created in "'''''input/domains/uvxx'''''". This file documents the QA issues detected for the domain, and mirrors the report generated for each Normative Edition and Ballot, but with the content filtered to that relevant to the specific domain being packaged. [Todo: Perform further testing on the filtering.]
| |
| − | | |
| − | ==Other support: VisioXML editing, and ??==
| |
| − | ===Updating class and attribute descriptions in Visio XML===
| |
| − | This release includes the transform to update Visio XML Descriptions in a “target” file based upon descriptions previously captured in a “source” file.
| |
| − | | |
| − | The matching is done on the Class name ( and attribute name within that class) for the non-Arrow classes. (All but Participation, ActRelationship and RoleLink.) For the Arrow classes, the algorithm finds the class away from which the arrow class is traversing (always a non-Arrow class) by its name,. and then matches the arrow class by the traversal name rather than by class name. (Thus “author” rather than “Author1”.) If the target also contains descriptions, there is a default option to Replace these, but this can be over-ridden so that the process will only bring in descriptions from the Source in those places that have no descriptions in the target.
| |
| − | | |
| − | In order to use this transform, you will have to re-define (and experiment) with the bat file named: XampleUpdateVisioXmlDescriptions-PublishLogged.bat. The BAT file has a set of parameters that must be set by preceding them with –DparameterName. The parameters are:
| |
| − | *'''''utilBaseDir''''' the directory that holds the target file(s)
| |
| − | *'''''utilDestDir''''' the directory to receive the results which will have the same name as the targets
| |
| − | *'''''utilSourceFileParameter''''' The full path and file name of the source file
| |
| − | *'''''utilTransformName''''' set this as -DutilTransformName=UpdateAnnotationsInVisioXml.xsl
| |
| − | *'''''utilTransformDir''''' you can ignore this, the default is correct
| |
| − | *'''''utilFileExt''''' the extension for the target files, set as -DutilFileExt=xml
| |
| − | | |
| − | '''Good Luck.'''
| |
Desktop Publication
The entire previous content of this page has been removed, as the tools it documented have been withdrawn in favor of a new V3 Publishing Tool Suite that can be downloaded from Gforge The new suite is documented underV3_Publishing_Process_Steps, whose is also included below.
V3 Publishing Steps
The steps described below document the various components of the publishing process, the reader can go here for simple run instructions
This section deals with the process of completing the installation process in Eclipse (if that is the environment), setting various configuration properties that characterize your computing environment to the publishing scripts (written and executed in ANT), and selected processes that can be invoked to reset the environment.
It is hard to know whether this should be the first step or the last step in the process. When viewed from the perspective of publishing a complete ballot, it is the first step, as this is where content is sent to HQ. However, from the facilitator's perspective it might be the final step, although in a procvess of iterative content refinement, it will probably be executed several times before final submission.
This section encompasses those steps undertaken by a Publishing Facilitator (or other person preparing part or all of a publication package) in order to assemble and "submit to publishing" their specific portion of the content. Note that in this context, "submit to publishing" means either to submit to HQ for publishing or to "submit" to oneself for local publishing.
The various content files repaired by the Work Groups must be preprocessed in order to make them useful in the publication. For example, the domain content must be extracted( as an XML file) from the publication database; the Visio "vsd" files from HL7's RMIM Designer must be processed to create appropriately sized graphics, and a hyper-linked HTML "map" to drive graphic navigation; etc. This section documents the processes used in preprocessing these files.
Version 3 publishing involves the aggregation of the variety of content that has been developed "in parallel" by a variety of work groups. As such, publication must include a series of processes, invoked iteratively, in which the content from multiple work groups is reviewed, corrected, aligned and perhaps constrained. This section documents these coordination and review processes. The details of the underlying design principles are documented as Design Principles for Alignment, Review and Constraint of V3 Publishing Content.
The HL7 V3 Generator is a tool whose primary purpose is to convert a set of domain and design content (frequently expressed in idiosyncratic xml formats, into a set of files expressed in the HL7 Model Interchange Format (MIF); and then to process the MIF files to create a supporting set of artifacts, such as static model schemas, table- and Excel- views of the static models, etc. This section covers the execution of the Generator processes.
"Specific content" refers to material that is the publishing responsibility of a single facilitator or Work Group. It might be many things - a domain, a CDA Implementation Guide or an "infrastructure" specification. This section documents the processes needed to publish this material.
"Common" content is all of the material that is part of a ballot or publication but is not the domains and specifications being voted upon. Examples include the Version 3 Guide, the Facilitator's Handbook, Introduction and Welcome sections,the table of contents used to navigate the ballot, etc.
This final section covers those processes that assemble the material into a coat curherent website, or build packages for distribution in zip files and/or electronic media.
GWBeeler 17:51, 12 August 2010 (UTC)
