Home

XML-centered Information Handling in Technical

1. Source Code plain text int Math area int width int height Figure 4 11 Workflow to generate Source Code from XML 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 56 4 3 4 PDF Rendering One of the most interesting points is to bring XML structured documents into a nice looking readable format To achieve that a technology described in section 2 4 is used the XSL Formatting Objects This XML vocabulary represents a page driven layout of your XML data In the future XSL FO may be the common lan guage for expressing the output format of XML documents across all kinds of software and hardware like web browsers or word processors either on a personal computer printer or even cell phone XML q markup text data markup text data valid XSL FO vocabulary binary data Figure 4 12 Workflow to generate PDF from XML The first step in this workflow is to transform XML structured data to an XSL FO valid vocabulary Therefore an XSLT has to be written that converts the XML vo cabulary of the technical document to Formatting Objects and that allows to define 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 57 the layout for that content to look exactly the way it is specified with the XSLT The second step in this process is to convert the formatting objects document into some other format that can be viewed onscreen or on paper This requires running a for
2. Abgesicherter Modus Ger te Manager Systeminformationen Leistungs berwachungstool Sicherheit can ts a Systemsteuerung Registrierungs Editor Glossar Windows Berichtsprogramm AG Informationen da Programmliste Gal Software Service Ga Windows 2000 Yerwaltungsprogramme NE Windows 2000 Support Tools Ga MS DOS Befehle KA Support Online und Informationen Ga bersicht ber Windows Scripting Host Tastenkombinationen Microsoft Eingabehilfen Windows Update MS DOS Systembefehle E Netzwerkmonitor Zus tzliche Supporttools auf der CD Siehe auch Figure 4 10 Windows HTML Help 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 55 4 3 3 Source Code A special case of transforming XML data to plain text would be to generate source code out of an XML document Of course it will hardly be possible to develop the whole source code of a project from XML But for example if specifications for a software are written in XML these could easily be extended to build header files or function bodies as shown in figure 4 11 In a large software project a lot of manual work could be automated in this way XML lt 4 markup text data lt function name area class Math gt lt param type int gt width lt param gt lt param type int gt height lt param gt lt return type int gt lt function gt
3. ferent This showcase also supports stylesheet parameters to alter the output of trans formations in different ways One of the possibilities of stylesheet parameters will be shown in section 5 7 1 However there are many other different things that 5 6 XSL TRANSFORMATIONS 70 can be achieved with these parameters like conditional text inside a document any kind of sort criteria can be applied to the document or actual dates or names can be passed into the document With the help of XSL transformations the user is also able to generate tables of content and dissolve cross references A full listing of a transformation providing this functionality can be found in appendix B A transformation can be applied the way it is shown in figure 5 9 First of all the XSLT that should be used has to be selected with a radio button Afterwards the stylesheet parameters and the output filename can be determined If no output filename is specified then the filename of the input file is used e Infineon SPIX Showcase Portal for Improved XML TechDoc Home Perform Transformation on book xml Upload Choose XSLT file Enter XSL Params e g date 10 01 2005 lang de Output filename c Wcombine2fo xsl Im c E combine2html sl Wcombine2xmi xsi ann Sl readme2fo xsl ln I cW utp2myXML xsl D Cr wa2fo xsl ee Transform Back Figure 5 9 Applying a transformation on a XML file For the server side transformations the XSL process
4. 85 lt Do the Section numbering gt lt xsl for each select section gt lt xsl variable name sectionnumber gt lt xsl number count section format 1 gt lt xsl variable gt lt fo block text align right gt lt fo inline keep with next within line always gt lt xsl value of select Schapternumber gt lt xsl value of select Ssectionnumber gt amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 lt fo basic link internal destination id color blue gt lt xsl value of select title gt lt fo basic link gt lt fotinline gt lt fo inline keep together within line always gt lt fo leader leader pattern dots leader pattern width 4Apt leader alignment reference area keep with next within line always gt lt fo page number citation ref id id gt lt fo inline gt lt j tO DO LOCKS lt xsl for each gt lt xsl for each gt lt xsl for each gt lt fo flow gt lt fo page sequence gt The code below copes with the content of each module specified inside the assem bly file 86 lt gt lt HH Content Hr gt lt gt lt xsl for each select book part gt lt xsl variable name chapternumber gt lt xsl number count part format 1 gt lt xsl variable gt lt xsl variable n
5. Product xml xml Information dtd egisters dtd xml TechDoc xml dtd Variables dtd TechDoc R amp D lt chapter gt lt paragraph gt lt table gt VHDL C lt row gt lt chapter gt Figure 4 4 Approach of a distributed DTD Disadvantages e Many XSLTs have to be maintained e If changes have to be made inside the global DTD all BUs must be informed and have to agree to these changes e Exchange of data between BUs is more difficult due to the fact that they use different XML vocabularies The second alternative uses nested DTDs In figure 4 5 a global Infineon Techni cal Documentation DTD is build up from smaller DTD components Advantages of nested DTDs 4 1 XML BASED TECHNICAL DOCUMENTATION 43 cS Sea een ee et A ML re use R amp D VHDL C Figure 4 5 Approach of a nested DTD e The DTD can be referenced by URI from all participants e XML reuse between BUs is possible e Single smaller DTDs can also be referenced e Easily extendable by adding new DTD components Disadvantages e Heavy impact on XSLTs when changes to the DTD are made e Double use of element names only becomes visible by validating against the global DTD e Versioning of global DTD is necessary 4 2 SINGLE SOURCING 44 A global decision on which of these two alternatives is best can hardly be made Considering all the pros and cons it depends on the commitments all parties con cerne
6. lt grammar xmilns http relaxng org ns structure 1 0 gt lt start gt lt ref name Book gt lt start gt lt define name Book gt lt element name Book gt lt ref name Title gt lt ref name Author gt PublishingDate gt lt oneOrMore gt lt ref name lt ref name Chapter gt lt oneOrMore gt lt element gt lt define gt lt define name Title gt lt element name Title gt lt text gt lt element gt lt define gt 2 2 STRUCTURE OF XML DOCUMENTS 14 lt define name Author gt lt element name Author gt lt text gt lt element gt lt define gt lt define name PublishingDate gt lt element name PublishingDate gt lt text gt lt element gt lt define gt lt define name Chapter gt lt element name Chapter gt lt attribute name ID gt lt element name ChapterTitle gt lt text gt lt element gt lt oneOrMore gt lt ref name Paragraph gt lt oneOrMore gt lt text gt lt element gt lt define gt lt define name Paragraph gt lt element name Paragraph gt lt attribute name ID gt lt text gt lt element gt lt define gt lt grammar gt RELAX NG is based on the generic concept of patterns Patterns are similar to XPath node sets a collection of nodes with an internal structure The difference between pat terns and the ot
7. gt lt fo table row gt lt xsl apply templates gt lt fo table row gt lt xsl template gt lt xsl template match cell gt lt fo table cell padding left 3pt padding right 3pt padding bottom 3pt padding top 3pt border top width 0 3mm border top style solid border bottom width 0 3mm border bottom style Tsolid gt lt fo block padding left 3mm gt lt xsl apply templates gt lt Fotblock gt lt fo table cell gt lt xsl template gt lt gt Here the reference to external figures is dissolved and they are included into the PDF document with the fo external graphic command The table around the figure is only used to get a nice looking border lt figure include H HHHHEFEEEEEEHEE gt lt xsl template match figure gt lt fo table space before 10pt table layout fixed width image width height image height border width 1 3pt border color black border style solid gt lt fo table column column number 1 column width proportional column width 1 gt AA A A A 92 fo table body gt fo table row gt fo table cell gt Fo block gt fo external graphic src image file content width image width content height image height gt lt fo external graphic gt lt fo block gt lt fo table cell gt lt fo table row gt lt fo table body gt lt fo tabl
8. In various articles published on the Internet as well as in IT and business journals the eXtensible Markup Language XML has been declared to be the standard that will revolutionize the Internet and electronic business The interest in getting a de tailed view on this new format the technologies associated with it and its use in electronic business led me to chose this as the subject of my thesis A project launched at Infineon Technologies AG is working on the conception and implementation of an XML based technical documentation and its publica tion via multiple channels Being part of the company s activities in the area of technical communication this interesting project has offered to me the possibil ities to gain experience in implementing XML technologies and to get to know the impacts of their use on a company s technical documentation processes The chief objective of this thesis was the implementation of a showcase providing an XML based editing environment for technical documentation Along with the implementation of this system practical experiences in using XML technologies should be gathered My proceedings at work started with examining a well defined goal for this the sis because technical documentation provides a huge area of possibilities After analyzing the current situation I decided to develop a XML enabled showcase for technical documentation I became acquainted with Adobe FrameMaker and how this software is use
9. One possible example 11 to illustrate the theory mentioned above and to show the differences between DTD XML Schema and RELAX NG could look like this one element named doc that holds two elements with the name elem The first one contains some text the second one should be an empty element xdoc gt lt elem gt Hello World lt elem gt lt elem gt lt doc gt This grammar cannot be described with a DTD because of the fact that an element has to be declared with a unique data type and cannot be declared in a content related way So either lt ELEMENT elem PCDATA gt or lt ELEMENT elem EMPTY gt has to be chosen Also the parent element doc does not allow a differentiation lt ELEMENT doc elem elem gt Even XML Schema would not be able to describe that grammar in a correct way when presumed that the number of occurrences of elem should not be restricted lt xs element name doc gt lt xs complexType gt lt xs sequence gt lt xs element name elem maxOccurs unbounded type xs string gt lt xs element name elem maxOccurs unbounded gt lt xs complexType gt lt xs complexContent gt lt xs restriction base xs anyType gt lt xs complexContent gt lt xs complexType gt 2 2 STRUCTURE OF XML DOCUMENTS 12 lt xs element gt lt xs sequence gt lt xs complexType gt lt xs element gt The validator would work correct for all the
10. Showcase Portal for Improved XML TechDoc Home a Qiimages 18 03 2005 book fo 11 04 2005 15 54 16 20590 Bytes edit gen pdf Upload Figure 5 11 Rendering a PDF from a FO file After the rendering process is done the final PDF looks like as it is shown in figure 5 12 To illustrate this example it is filled with sample data about the history of transistors Nevertheless the book contains a table of contents now and all the cross references were dissolved However this should not distract from the fact that many different document types like those listed in section 3 2 can be generated and published with the help of this workflow 5 7 1 Linking to Source Documents To enable the process of reviewing documents without sending them back and forth per mail a feature has been implemented to generate a sort of preview PDF document It looks exactly the same way as the PDF document that is generated for publishing but in addition it provides edit source links on the right hand side of the document border When clicking on one of these links the source document that provides the content for this part of the PDF document is opened right away for editing in the showcase portal This feature really supports the idea of single sourcing because with one click 5 7 PDF GENERATION 73 JORR M gt o gt DOR Be 8 20a Infineon technologies 1 Development of the Transistor 1 1 Transistor The transistor is a solid state s
11. lt xsl variable gt lt xsl param gt and lt xsl with param gt using the as attribute The as attribute tells the XSLT processor to check the data types of the variables or parameters and convert them to the specified 2 4 XSL FO 20 data types This early runtime check prevents further processing of bad data and the un expected results that may be difficult to debug To use these data types it is necessary to include the XML Schema namespace URI along with the other namespace declarations in the start tag of lt xsl stylesheet gt A small example is listed below to show the use of this functionality lt xsl stylesheet version 2 0 xmlns xs http www w3 org 2001 XMLSchema xmlns xsl http www w3 org 1999 XSL Transform gt lt xsl variable name num select Order Item number as xs integer gt User defined functions XSLT 2 0 introduces the ability for users to define their own functions which can then be used in XPath expressions This is an extremely powerful mechanism that should prove to be very useful Stylesheet functions as they are called are defined using the lt xsl function gt element This element has one required attribute called name It contains any number of lt xsl param gt elements followed by zero or more lt xsl variable gt elements followed by exactly one lt xsl result gt element This restricted content model may sound limiting but the true power lies in the use o
12. 02 2005 08 54 38 118 Bytes view edit content edit table edit transform validate pcb xml 14 02 2005 08 20 18 69843 Bytes view edit content edit table edit transform validate team xml 06 04 2005 10 56 22 502 Bytes view edit content edit table edit transform validate Figure 5 4 Features on XML files For opening up a XML file in view mode which supports syntax highlighting use the view button beside that file The XML file will then be displayed as shown in figure 5 5 5 3 ONLINE EDITING 65 er SPIX Showcase Portal for Improved XML TechDoc lt xml version 1 0 encoding ISO 8859 15 gt A lt chapter id ch1 gt lt title gt Development of the Transistor lt title gt lt section id sectO gt lt title gt Transistor lt title gt lt paragraph gt The transistor is a solid state semiconductor device which can be used for amplification switching voltage stabilisation signal modulation and many other functions It acts as a variable valve which based on its input current BJT or input voltage FET allows a precise amount of current to flow through it from the circuit s voltage supply lt paragraph gt lt paragraph gt In essence it has three terminals lt crossRef Idref CEGHDIBB type FigureTitle gt A current or voltage applied through across two terminals controls a larger current through the other terminal and the common terminal In analog circuits transistors are used in amplifiers Analog circuits
13. 2002 cip uni trier de lange semxml semarb html 2005 07 26 David Mertz XML Matters Kicking back with RELAX NG February 2003 www 128 ibm com developerworks xml library x matters25 html 2005 07 26 Eric van der Vlist RELAX NG December 2003 books xmlschemata org relaxng page2 html 2005 08 05 W3C Recommendation XML Path Language XPath November 1999 www w3 org TR xpath 2005 05 28 Evan Lenz What s New in XSLT 2 0 April 2002 www xml com pub a 2002 04 10 xslt2 html 2005 07 26 Jinyu Wang Five XSLT 2 0 Features that Simplify XML Document Transformations 2005 www oracle com technology pub articles wang_xslt html 2005 07 26 Sudhir Mangla Beginners Introduction to ASP NET August 2003 www devhood com tutorials tutorial_details aspx tutorial_id 768 2005 05 28 MSDN Library Introduction to ASP NET 2005 Microsoft Corporation msdn microsoft com library default asp url library en us cpguide html cpconIntroductionToASP asp 2005 05 28 BIBLIOGRAPHY 100 19 20 21 22 23 24 25 26 27 28 John Kopp C Tutorial Introduction cplus about com od learnin2 1 aa020804a htm 2005 05 28 Joey Mingrone An Introduction to C devcentral iticentral com articles CSharp intro_Csharp default php 2005 05 28 Pankaj Kamthan and Hsueh Ieng Pai Perspectives of XML in E Commerce December 2000 parallel rw docs Internet IRT articles js215 index htm 2005 05 28 Benoit Marcha
14. Technologies AG in Munich the scientific support was done by the Institute for Information Systems and Computer Media at Graz University of Technology Grateful acknowledgements are made to the many people whose help in preparing this thesis was invaluable In partic ular my technical supervisor Ingo Schreiber and my scientific supervisor Harald Krottmaier I would also like to thank my parents for their assistance and for mak ing my studies possible and my girlfriend Lisa because her encouragement was a great source of inspiration throughout my studies Table of Contents Abstract Abstract in German Acknowledgements 1 Introduction 2 Used Technologies 3 21 22 2 3 2 4 29 AMG a a Bera Soe Aa Ba D SS OS eS AS Structure of XML documents 2 43 2 Re 24 0 2 21 Document Type Definition 2 oe a a Ghee Ses es 222 AML SCDE 2 222 Sod ws Bs Be EA Se Be EB ek de a Cie BELANGE a Sete an Gea So Bea wm Seam Re XSLT e Sys Gb Bee ae ee RRR ER En a Eu 2 Moll WOVE ALA 2 nestu rdu shere ES XSLFO os e Sx eH eS en RE eee OS eee SC ABP INET and CH 56 See SR amp Su ab eS en a The Present 3l ae 33 The Roleof IT BT ec eos meed ore der ena ea The current Process in Technical Documentation 3 2 1 FrameMaker in structured mode 3 2 2 Use of FrameMaker s XML export Concho 2 30 0 be eRe 2 ee he he RE ee iv ii iii TABLE OF CONTENTS 4 The Future 4 1
15. annotations While PDF is only a defacto standard it is almost universally used for online delivery of print quality documents PDF includes a number of useful features for online display including navigation bookmarks and hyperlinks The FO specifi cation does not provide any direct facilities from which these PDF artifacts could be derived However all the FO implementations provide extensions for creating bookmarks links and other PDF specific online artifacts 60 Chapter 5 Showcase Portal One of the main targets of this thesis was the development of a showcase that demonstrates how XML based technical documentation could be realized in the near future The features of server side transformations and PDF generation were also a main part of this work always considering the aspects of single sourcing 5 1 Design After collecting all requirements for this showcase the design was set up Due to the fact that many authors should work in a single sourcing environment that should enable them to re use and assemble their documents out of XML compo nents the decision to implement the whole showcase as a web application was made Figure 5 1 shows the units that this showcase is built of The validation part is used to validate XML documents against DTDs or XML Schema if none of these is declared inside the file it is checked at least for well formedness DTDs and Schemata are stored inside the portal as well as the trans formation
16. compressed form at the end of the document e generating SVGs which for example draw a pin assignment out of tabular data After the transformation the XML documents are imported into FrameMaker to continue the work inside the FrameMaker environment Figure 3 3 points out the workflow de scribed above and should show that this is rather a workaround than something suitable for productive use 3 3 CONCLUSION 31 FM document y gt XML XML y FM document Figure 3 3 The use of the FrameMaker XML import and export 3 3 Conclusion Concluding it can be said that the tools described above and how they are used in technical documentation today is something that evolved over the years It is almost impossible to replace such a system from one day to another However a prediction can be made that the use of Adobe FrameMaker in structured mode together with an EDD Read Write rules and various XSLTs will become far to complex to be handled efficiently over the time And therefore I believe that it is an reasonable effort to take a closer look on possible alternatives 32 Chapter 4 The Future This chapter is going to point out how Technical Documentation could be done in the future on the basis of a XML based environment Changes brought about with the in troduction of XML and the advantages and disadvantages of this new technology will be shown Most of the information has been der
17. create a finite set of such tags is doomed to failure Instead XML allows developers and writers to invent ele ments they need As a reminder the X in XML stands for eXtensible Extensible means that the language can be extended and adapted to meet many different needs For instance A mathematician would be able to describe any formula in XML Chemists can use elements that describe molecules atoms reactions and other items encountered in chemistry and technical writers can use the meta lan guage for structuring their documents XML fulfills the following definitions of a meta markup language e Flexible Data Structure The language is not based on a restricted set of tags and elements It can be extended to satisfy the needs of many different purposes and it can easily be converted to many different formats e Platform Independence Data defined with XML can be used edited and processed on any platform without taking care of system specific charac teristics e Textorientation Due to the platform independent aspect a storage as binary data is not possible Therefore the information is stored in plain text and the markup is distinguished through special characters Although XML is flexible in the elements it allows to be defined it is quite strict in many other aspects It provides a grammar for XML documents that defines where tags may be placed what they must look like which element names are legal how attributes are attached
18. figure gt lt paragraph gt lt section gt lt section id sect1 gt lt title gt Invention lt title gt lt paragraph gt The transistor was invented at Bell Telephone Laboratories in December 1947 first demonstrated on December 23 by John Bardeen Walter Houser Brattain and William Bradford Shockley who were awarded the Nobel Prize in physics in 1956 Ironically they had set out to manufacture a field effect transistor FET predicted by Julius Edgar Lilienfeld as early as 1925 but eventually discovered current amplification in the point contact transistor that subsequently evolved to become the bipolar junction transistor BJT lt paragraph gt lt Section gt lt section id sect2 gt lt title gt Types lt title gt lt paragraph gt lt list gt lt item gt Semiconductor material lt item gt 80 Broadly speaking transistors are categorised as follows germanium silicon gallium arsenide lt item gt Physical packaging through hole metal through hole plastic surface mount ball grid array lt item gt lt item gt Type BJT JFET IGFET MOSFET other types lt item gt lt item gt Polarity NPN N channel PNP P channel lt item gt lt item gt Maximum power rating low medium high lt item gt lt item gt Maximum frequency capability low medium high radio lt
19. files But they should not be edited or extended by the authors them selves Instead some sort of management level should ensure the consistency of the XML documents inside the working environment This management should also adapt the XSL files if something is changed inside the XML vocabulary that is currently used The transformations are used in many different ways and provide very versatile functionality they can be used to publish technical documents or generate source 5 2 FUNCTIONAL OVERVIEW 61 validated Documents SW Authoring Management Publishing Development Figure 5 1 Structure of the showcase code for different language types but they are also used for previewing written content in a quick and easy way 5 2 Functional Overview This section gives a short overview of how the information inside the portal should be structured to achieve good results First of all a high level hierarchy is a good starting point this is mainly done to categorize the content inside the portal in a certain manner In this example shown in figure 5 2 the division on the root level has been done according to the distribution of Infineons Business Units BU Although this division does not prevent the use of content modules across different BUs It is an advantage to keep a common working environment one level below the root As pictured in figure 5 3 the directory structure on this level support
20. gt lt xs sequence gt lt xs complexType gt lt xs element gt lt xs schema gt The only disadvantage of XML Schema is that it can get quite complex and hard to maintain if your amount of different elements attributes and their data types is very large 2 2 3 RELAX NG The Regular Language description for XML New Generation RELAX NG 8 emerged from e RELAX Core 9 developed by Murata Makoto and e Tree Regular Expressions for XML TREX 10 developed by James Clark The work on these two developments listed above has been discontinued In the year 2001 they were unified and further on developed under control of the Orga nization for the Advancement of Structured Information Standards OASIS The goal was to create a competitive alternative to the XML Schema Language RELAX NG has been built from a scientific basis that deals with regular tree grammars XML documents can be seen as context free grammar for strings but in fact a XML document is the string representation of a tree structure and there fore tree grammars are ideal for representing a XML document structure XML Schema can only describe a subset of regular tree grammars so called single type grammars DTDs are even more limited they can only describe a sub set of single type grammars so called local tree grammars Therefore one of the main advantages of RELAX NG is that it can describe every regular tree grammar 2 2 STRUCTURE OF XML DOCUMENTS 11
21. in dustry that designs develops manufactures and markets a broad range of semiconductors and complete system solutions targeted at selected industries Their products serve applications in the wireless and wireline communications automo tive industrial computer security and chip card markets Their product portfolio consists of both memory and logic products and includes digital mixed signal and analogue inte grated circuits ICs as well as discrete semiconductor products and system solutions 3 1 The Role of IT BT IT BT represents the IT line that executes those projects that are proposed as demands from the different Business Units and fulfill the project approval process RDS is the department that attends projects and applications belonging to the Research and Develop ment area This thesis has been written at the RDS department in the area of Technical Communication and therefore I will give a short introduction about the situation that I met when I was starting my diploma thesis and elaborate on how technical documentation is done at Infineon throughout the various Business Units 3 2 THE CURRENT PROCESS IN TECHNICAL DOCUMENTATION 26 3 2 The current Process in Technical Documenta tion This chapter will provide an overview on Infineons technical documentation in general as well as an insight into the current documentation process The current documentation processes are optimized for the production of print media The tec
22. in semiconductor indus tries and has more than 30 000 employees world wide is indeed a very interesting experience It gave me a number of great new impressions and opened my view on some sort of problems that will probably never be encountered in a smaller company The people in the department I was working at were really very supportive and they always encouraged me in my work Additionally they gave me good and honest feedback for a number of smaller presentations I made throughout the whole time at Infineon Technologies Concluding I can say that I have learned much more than just plain technical knowledge during the writing of this thesis 78 Appendix A XML Documents The XML source files of the examples used in chapter 5 are listed here book xml is an example of an assembly file that combines two chapters to a complete book lt xml version 1 0 encoding ISO 8859 15 gt lt book gt lt part link chapter chl xml gt lt part link chapter ch2 xml gt lt book gt ch1 xml an example file for XML structured content including chapter section list and cross reference elements lt xml version 1 0 encoding ISO 8859 15 gt lt chapter id ch1 gt lt title gt Development of the Transistor lt title gt lt section id sect0 gt lt title gt Transistor lt title gt lt paragraph gt The transistor is a solid state semiconductor device which can be used for amplifica
23. is easily possible to get lost in the amount of different elements and when writing content it comes out to spending more time with tagging a single piece of infor mation than actually writing content On the other hand if a document is structured to roughly the ability to reuse pieces of information is lost and together with that the advantage of single sourc ing It sometimes is a bit tricky but it is important to keep the balance when planning how to structure technical documents 4 2 3 Reasons for Single Sourcing If planning and implementation is done properly single sourcing can save time and money If once single sourcing is established it enables the development of content and the reuse in many different ways When reusing the same content in different formats for different audiences and purposes reduction of duplicate work is achieved For example when developing a printed manual and an online help system for the same product both documents will contain very similar information only the 4 2 SINGLE SOURCING 47 formats differ If development of these two documents is done separately the same work is done twice But if content modules are used instead there is no need to do the work for both formats separately this cuts down the workload When using single sourcing the right way it does more than just reducing work load it also increases flexibility Imagine a project that at the beginning targets the development of an
24. machine to machine and human to machine interface due to its markup characteristics following a strict syntax XML is a data representation that has the char acteristics of a document This document could be a file a record in a relational database or a stream of bytes arriving at a network socket The concept is very powerful because it implies that the same information can be processed data view or can be presented document view in the same application at the same time Even though it is expected that large documents will be processed by machines they are still human interpretable 21 4 1 8 Business to Business Communication XML simplifies business to business communication particularly for the following rea sons 1 The only thing that is to be mutually agreed upon is the XML vocabulary that will be used to represent data 2 Neither company has to know how the other s back end systems platforms operat ing systems programming languages are organized which does not put any extra technical burden while keeping the privacy All that is required is that each com pany develop the mapping to transform XML documents into the internal format used by the back end systems 4 1 XML BASED TECHNICAL DOCUMENTATION 35 3 XML based solutions are scalable If there is an addition of another partner there is no need by the host company to interact with the systems of the new company All that is required is that they follow the protocol
25. online help system for a specific product After half of the work is done the possibility to provide a printable version of the online help system should also be guaranteed This new requirement would be hard to fulfill if the help system would have implemented in HTML for instance A system would have been developed where content and layout is mixed together Due to the advantages of single sourcing the development of this online help system has already been implemented with XML and with the use of XSLTs it is provided to the web And because of the clear separation of content and formatting it is now possible to provide a printable version of the help system with little more effort This simple example shows that single sourcing also increases flexibility 4 2 4 Improved Document Assembly Single sourcing used in an XML environment provides another advantage The document assembly does not have to be done by hand anymore XSLT gives the user a powerful technology at hand that is able to combine modular content chunks to a single output file Only an assembly file is needed anymore where your content chunks are ref erenced in And if a XSLT is used on that file the output would be a properly formatted document including the dereferenced content Figure 4 6 illustrates this workflow 4 2 5 Evaluating Single Sourcing While single sourcing can help companies reduce costs and improve quality im plementing it requires research and pla
26. special software converts some custom XML output format like XSL FO to what you actually want An alternative to a transformation based presentation is to provide a descriptive stylesheet that simply states how each element in the original document should be formatted This is the realm of Cascading Style Sheets CSS This works partic ularly well for narrative documents where all that is needed is a list of the fonts styles sizes and so on to apply to the content of each element The key is that http www omnimark com 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 51 when all markup is stripped from the document what remains is more or less a plain text version of what you want to see No reordering or rearrangement is necessary This approach works not very well for data oriented documents where the raw content may be nothing more than an undifferentiated mass of numbers dates or other information that is hard to understand without the context and annota tions provided by the markup However in this case a combination of the two approaches works well First a transformation can produce a new document con taining rearranged and annotated information Then a CSS stylesheet can apply style rules to the elements in this transformed document 4 3 1 HTML The HyperText Markup Language HTML derives from the same family of markup languages as XML does That means that the transformation from XML data to HTML is a direct one t
27. tp certId server_cert gt lt tp ClientSecurityDetailsRef tp securityId tp_security gt lt t lt t lt i tp TransportServerSecurity gt tp TransportReceiver gt Up Transport gt lt tp Transport tp transportId smtp_connection gt lt tp TransportReceiver gt lt tp TransportProtocol gt SMTP lt tp TransportProtocol gt lt tp Endpoint tp uri mailto ebxml coyote com lt i lt i tp type allPurpose gt tp TransportReceiver gt tps Transp rt gt 4 1 XML BASED TECHNICAL DOCUMENTATION 40 The transport elements specify the protocol in use tp TransportProtocol the ad dress of the server tp Endpoint and optionally security information tp Transport ServerSecurity In the example above the HTTP connection is secured through SSL the SMTP connection is not Every organization has a CPP Coyote has one but its business partner ACME Manufacturing also has one To establish the electronic relationship between the two it suffices to look up the commonalities in the two CPPs Software can very easily establish the match Suppose ACME s CPP states that ACME supports HTTP then the software finds a match and it can configure itself for HTTP Since the CPP contains the address of the server and the security parameter the configuration requires no human in tervention For simplicity the above example has concentrated on transport proto cols because that is where you ne
28. which is represented by the XML vocabulary 4 1 8 1 ebXML One of the technically mature and wide spread standards for B2B communication on XML basis is Electronic Business using eXtensible Markup Language ebXML The following information is derived from the ebXML homepage ebXML is a modular suite of specifications that enables enterprises of any size and in any geographical location to conduct business over the Internet Using ebXML companies now have a standard method to exchange business messages conduct trading relation ships communicate data in common terms and define and register business processes ebXML provides e The only globally developed open XML based standard built on a rich heritage of electronic business experience e Creates a single global electronic market that enables all parties irrespective of size to engage in Internet based electronic business e Enables parties to complement and expand electronic business to new and existing trading partners e Facilitates convergence of current and emerging XML efforts ebXML delivers the value by e Developing technical specifications for the open ebXML infrastructure e Creating the technical specifications with the world s best experts e Collaborating with other initiatives and standard development organizations e Building on the experience and strengths of existing Electronic Data Interchange EDI knowledge e Enlisting industry leaders to participate and a
29. xsl template gt lt Section Label HEHE HE FE AE FE HE HE HEH HEHE EH E E HE E EE E H gt lt xsl template match section mode label1 gt lt xsl value of select title gt lt xsl template gt lt paragraph EAA AHE A i A TEH H E EA H E A H E E HE HEH HH HEH lt xsl template match paragraph gt lt fo block font family Helvetica font size 10pt text align justify space before optimum lem space before minimum 0 8em space before maximum 1 2em gt lt xsl apply templates gt lt tovhloek gt 89 lt xsl template gt In this part of the code cross references are dissolved and a internal link pointing to the target of the reference is inserted lt CrossRef Hr gt lt xsl template match crossRef gt lt xsl variable name thisref gt lt xsl value of select Idref gt lt xsl variable gt lt fo basic link internal destination Idref color blue lt xsl apply templates select x id Sthisref mode label i gt lt fo basic link gt lt xsl apply templates gt lt xsl template gt lt Lists gt lt xsl template match list gt lt fo list block padding after 12pt space after minimum 12pt space after 12pt gt lt xsl for each select item gt lt fo list item gt lt fo list item label end indent label end gt lt fo block font family Helv
30. 4 11 4 12 3 1 3 2 3 5 4 32 Hype Cycle for XML Technologies 2003 6 The workflow of an XSL transformation 16 XSL FO Parts of an XSL FO area 2 ee eee ee es 21 Internal documentation process 222 none 21 FrameMaker in structured mode 22 22 2222er 30 The use of the FrameMaker XML import and export 31 An Electronic Business Scenario without ebXML 36 An Electronic Business Scenario withebXML 31 FrameMaker is not capable of writing modular DTDs 41 Approach of a distributed DID 2 2 zz zu bee ewes 42 Approach of a nested DTD 2 we eee u as oe es 43 Example of an assembly file 2 4228 548624404 64 48 Survey results Use of single sourcing solutions 49 Workflow to convert XML toHTML 52 Workflow to convert XML to CHM 53 Windows HIML Help 24 626 22 54 2 KREG REARS lt 4 4 54 Workflow to generate Source Code from XML 55 Workflow to generate PDF from XML 56 Structure of the showcase cee ieh eek oe ere 61 Division according to Business Units 62 Directory structure fora XML based environment 63 Features on XML MES lt e m st sA Gow Gon Gon Gone Bo 64 Viewing mode of a XML file 2 4 Han 65 96 LIST OF FIGURES 97 5 6 Dal 5 8 39 5 10 11 3 12 313 5 14 Online editing mode 2 2 ge Ss ee eee ee ee SS 66 Content editing mode sau 2a HH Re
31. 4 2 4 3 XML based Technical Documentation 4 1 1 Standardization 25a as ea a a a aa es 4 1 2 Manageability 4 besessen 4 13 Dane e poce eroe Be aa Re an ER hs 4 1 4 Extensibility 1 ee ae rs 4 13 EVERIO s sos e saa en sa kenne 4 1 6 Decoupling Structure and Presentation 4 1 7 Human to Machine and Machine to Machine Interfaces 4 1 8 Business to Business Communication 419 Modular DTD ur ee ao we EI OO A Sinple COMES o ce eee DEMS Ce a 421 Condions are Re eS CG 422 Granulanty of Structure 2 24d cbc eed enw aha t 4 2 3 Reasons for Single Sourcing 4 2 4 Improved Document Assembly 4 2 5 Evaluating Single Sourcing Transformation to different Output Formats 431 BIME 5 su 4 38H RR EHH SERRE ES RES 4 3 2 Windows Help file 2 2 2 CE nenn 433 BIBECDIE oak cocs pa dank fenk doe bate rd 434 PDF Benger u 2 ey eier 5 Showcase Portal Jd 32 5 4 as 5 6 3 7 Online Bine aan area pe Content Editing ss as a a Ra a Ra aa Tabular FOU 2 4 ae a XSL Transformations 0 0000 ee eee PDF Generation ee BR BS BO OS 3 7 1 Linking to Source Documents u 2 46 see ek 0 TABLE OF CONTENTS 6 Conclusions 6 1 General Aspects 6 2 Personal Impressions Appendices A XML Documents B XSL Transfomation List of figures Bibliography vi 76 76 27 78 78 82 97 98 Chapter 1 Introduction
32. C 22 boxes to create and where to place them In the process it will split the large blocks which the XSL FO document describes with block elements into smaller line and glyph areas It may also split single block areas that the XSL FO document describes into multiple block areas if a page break is required in the middle of a large block although XSL FO does let the user prevent these breaks if necessary The formatter also generates the correct number of pages for the content that is found In short the XSL FO document contains hints and instructions that the formatter uses to decide what items to place where on which pages More information on XSL FO proces sors can be found in section 4 3 4 Concluding it can be said that with Formatting Objects and a sophisticated XSL FO processor really good looking printable documents can be generated that can take it on with the output of any What You See Is What You Get WYSIWYG program 2 5 ASP NET and C ASP NET is more than the next version of Active Server Pages ASP 17 Because it has evolved from ASP ASP NET looks very similar to its predecessor but only at first sight Some items look very familiar and they may remind of ASP But concepts like Web Forms Web Services or Server Controls gives ASP NET the power to build real Web Applications It provides a unified Web development model that includes the services necessary for developers to build enterprise class Web applic
33. Diploma Thesis XML centered Information Handling in Technical Documentation Michael Ebner Graz June 2005 Assessor o Univ Prof Dr Dr h c mult Hermann Maurer Institute for Information Systems and Computer Media Graz University of Technology Supervisors Dipl Ing FH Ingo Schreiber Munich Infineon Technologies AG Univ Ass Dipl Ing Dr techn Harald Krottmaier Institute for Information Systems and Computer Media Graz University of Technology Diplomarbeit XML zentriertes information handling in der Technischen Dokumentation Michael Ebner Graz Juni 2005 Begutachter o Univ Prof Dr Dr h c mult Hermann Maurer Institut fiir Informationssysteme und Computer Medien Graz Technische Universitat Betreuer Dipl Ing FH Ingo Schreiber Miinchen Infineon Technologies AG Univ Ass Dipl Ing Dr techn Harald Krottmaier Institut fiir Informationssysteme und Computer Medien Graz Technische Universit t I hereby certify that the work presented in this thesis is my own and that work performed by others is appropriately cited Ich versichere hiermit diese Arbeit selbst ndig verfa t andere als die angegebe nen Quellen und Hilfsmittel nicht benutzt und mich auch sonst keiner unerlaubten Hilfsmittel bedient zu haben Signature of the author Abstract This diploma thesis has been developed at Infineon Technologies AG in Munich Germany The aim was to examine the existing systems used for te
34. ML format like PostScript XML s major transformation language is the eXtensible Stylesheet Language Trans formations XSLT However XSLT is not the only transformation language you can use with your XML documents Other stylesheet languages such as the Docu ment Style Semantics and Specification Language DSSSL 26 are also available So are a variety of proprietary tools like OmniMark Most of these have particu lar strengths and weaknesses for particular kinds of documents Custom programs written in a variety of programming languages such as Java C Perl and Python can also be used to transform documents This is some times useful when you need something more than a simple transformation for instance interpreting certain elements as database queries and actually inserting the results of those queries into the output document However the biggest fac tor when choosing which tool to use is simply which language and syntax you re most comfortable with There are many different choices for the output format from a transformation A PostScript file can be printed on paper overhead transparencies slides A PDF document can be viewed in all these ways and shown on the screen as well Sim ple HTML has the advantages of being very broadly accessible across platforms and being very easy to generate via XSLT from source XML documents Gener ating a PDF or a PostScript file normally requires an additional conversion step in which
35. RANSFORMATIONS 69 eo Infineon SPIX Showcase Portal for Improved XML TechDoc Home Teel chapter title id FET Families ch2 paragraph paragraph_Text FETs are divided into two families junction FET JFET and insulated gate FET IGFET also known as metal oxide silicon or semiconductor FET MOSFET Unlike IGFETs the JFET gate terminal forms a diode with the channel semiconductor material between source and drain Functionally this makes the N channel JFET the solid state equivalent of the vacuum tube triode which xl cimilarle farme a dinda hatmaan ite arid and aathade FETs are further divided into enhancement mode and a depletion mode types Mode refers to the polarity of the gate voltage with respect to the source when the device is used for linear amplification Taking N channel FETs in depletion mode the gate is negative with respect to the source while in enhancement mode the gate is positive For both modes if the gate voltage is made more xl nacitive the courealfdrsin currant mill inerasca For D Figure 5 8 Tabular editing mode 5 6 XSL Transformations Another feature of this showcase is that it provides server side XSL transforma tions Virtually any kind of transformation can be used on XML files As stated in section 4 3 many different output types of these transformations are possible the result can be either a XML formatted document or something completely dif
36. Re a 67 Tabular editing mode 2 2 22 eee eee ie ee ei ei 69 Applying a transformation on a XML file 70 Example of an assembly file 2 2 bee Rw BRS 684 71 Rendering a PDF from a FO file rer 72 Final book pdf generated completely out of XML data 13 Activate the edit source functionality 74 An editable PDF document 2 6 4 oe 20 as a sea 75 BIBLIOGRAPHY 98 Bibliography 1 T Bray J Paoli C M Sperberg McQueen and E M eXtensible Markup Language XML 1 0 Technical report World Wide Web Consortium W3C October 2000 www w3 org TR REC xml 2005 05 28 2 SGML international standard iso8879 1986 3 R Knox C Abrams W Andrews T Friedman K Harris A Linden D Logan M Knox and R Wagner Hype Cycle for XML Technologies May 2003 4 E Rusty Harold W Scott Means XML in a Nutshell 3rd Edition September 2004 5 Dick Kevin XML A Managers Guide Addison Wesley USA 2000 p 13ff 6 W3C XML Schema www w3 org XML Schema 2005 05 28 7 Priscilla Walmsley XML Schema An Overview Januar 2002 www informit com articles article asp p 25002 2005 05 28 8 RELAX NG www relaxng org 2005 05 28 9 RELAX Core www xml gr jp relax 2005 07 26 BIBLIOGRAPHY 99 10 11 12 13 14 15 16 17 18 TREX www thaiopensource com trex 2005 07 26 Christoph Lange XML Dokumenttypen mit Schema Sprachen beschreiben May
37. aluate the interest in this future product e The Data Sheet is created based on data from the PRD and the specifications mentioned above Depending on the Business Unit either all information related to the technical characteristics and functionalities is being described in a so called Data Book or in a Data Sheet combined with a separate User Manual For less complex products only a Data Sheet is being used e The Application Notes are created by the Application Engineers based on the information from the Design Specification documents Application Notes contain information on possible uses of the products e Errata Sheets contain corrections of Data Sheet errors e User Manual is a document for novice users that explains how to use or operate a product Usu ally organized topically or by task 3 2 THE CURRENT PROCESS IN TECHNICAL DOCUMENTATION 29 3 2 1 FrameMaker in structured mode As described above technical documentation at Infineon is done with Adobe FrameMaker mainly FrameMaker is a professional level desktop publishing package it provides a large feature set for publishing to both paper and electronic formats FrameMaker s for matting engine allows users to do complex text formatting and page layout With the ver sion of FrameMaker 7 1 a so called structured mode has been introduced This means that FrameMaker allows the user to define structural elements like chapters paragraphs figures tables or any other ki
38. ame filePath select Q ink gt This xsl for each dissolves every chapter that is included inside the assembly file and opens the required document to process the content stored inside lt xsl for each select document link chapter gt lt fo page sequence master reference A4 gt lt xsl call template name draw page header gt lt xsl call template name draw page footer gt lt fo flow flow name xsl region body gt lt Harrer Chapter header HHHHFHEFEEE gt for block id 0id gt lt fo block font family Helvetica gt lt fo block font size 14pt font weight bold gt lt fo table space before 5pt gt lt fo table column column width 16cm gt lt fo table column column width 2cm gt lt fo table body gt lt fo table row gt lt tro rable cell gt lt fo block gt lt xsl value of select Schapternumber gt amp x00a0 amp x00a0 amp x00a0 amp x00a0 lt xsl value of select title gt 87 lt o block gt lt fo table cell gt lt fo table cell gt Here the actual test for an editable PDF is done If the editsource parameter is set to true then an external link is included that points to the XML source document that lies behind this part of the PDF lt Test if edtiable is enabled or not gt lt xsl if test Seditsourc
39. ations While ASP NET is largely syntax compatible with ASP it also provides a new programming model and infrastructure for more scalable and stable applications that help provide greater protection You can feel free to augment your existing ASP applications by incrementally adding ASP NET func tionality to them ASP NET is a compiled NET based environment you can create applications in any NET compatible language including Visual Basic NET C pronounced C sharp and JScript NET Additionally the entire NET Framework is available to any ASP NET application Developers can easily access the benefits of these technologies 18 John Kopp describes the NET technology in his C introduction 19 as follows The two main elements of NET that represent the widest shift from previ ous Windows based environments are the common language runtime CLR 2 5 ASP NET AND C 23 and the NET framework class library With older languages such as C source code code that programmers write is compiled or turned into a ma chine specific module usually referred to as an executable or a binary This module will run only on a particular operating system A Windows program will not run directly on Unix for instance C is compiled into an intermedi ate form called the Microsoft Intermediate Language MSIL The MSIL is run within the common language runtime The common language runtime in turn converts the MSIL into commands or code that
40. author of the XML document has to take care of the semantic meaning of the markup very carefully Due to the fact the user enters information into this document in content editing mode only the markup tags will give a clue which information has to be entered into a specific field 5 5 Tabular Editing Tabular editing gives user and author another method to enter or modify the con tent of a XML document Tabular editing is based on the technology of treemaps The term treemap describes the notion of turning a tree into a planar space filling map 29 These treemaps are able to represent a tree structured information this applies to any well formed XML document as nested areas When calling the tabular editing function on a XML file inside the portal this file is parsed and the XML structure is stored internally The storage takes place inside the servers memory and the structure of the file is represented as linked ta bles Afterwards a procedure is called on these linked tables that runs recursively through them and builds a web form consisting of nested HTML tables As described in section 5 4 attribute and element values are also editable fig ure 5 8 pictures that Again when saving this web form the information is stored directly back into the XML file Due to some limitations in the ASP NET XML support this editing mode cannot cope with XML documents that uses same ele ments in different depths of a tree structure 5 6 XSL T
41. chnical doc umentation and to build a showcase emphasizing the work with documents in an XML based environment Implementing the idea of single sourcing and combin ing it with the possibilities XML provides it shows that it is now possible to take advantage of the benefits that evolve from these two technologies All this has been realized in a web application that supports various forms of online XML editing and also provides server side validation and transformation In addition a rendering engine has been included that is able to turn XML data into printable PDF documents ii Abstract in German Diese Diplomarbeit wurde bei der Infineon Technologies AG in M nchen ent wickelt Das Ziel war es die dort zur technischen Dokumentation verwendeten Systeme zu untersuchen und aufbauend auf den Ergebnissen einen Showcase zu entwickeln der die technische Dokumentation in einer XML basierten Umge bung unterst tzt Es wurde die Idee des sogenannten Single Sourcing mit den M glichkeiten die XML bietet kombiniert um die Vorteile dieser beiden Tech nologien zu nutzen Der Showcase wurde in einer Web Applikation umgesetzt die verschiedene M glichkeiten der online XML Editierung bietet und ebenfalls eine serverseitige Validierung und Transformation unterst tzt Desweiteren wurde ein Programm eingebunden das es erm glicht XML Daten in ein PDF Dokument zu konvertieren iii Acknowledgements This diploma thesis was conducted at Infineon
42. cope with the ideas and consequences of functional programming Transformation in this context means that an amount of information is transformed into another form of data representation considering a specific set of rules If it is not intended to transform the whole amount of information a preselection has to be done before With the help of XPath a subset of nodes can be selected from a document therefore XSLT has a strong relationship with XPath For more information on XPath please refer to the specification at W3C 14 The output of an XSL transformation is described with an XSLT stylesheet Such a stylesheet is a well formed XML document that uses special XSLT keywords and in structions These instructions are interpreted and executed with an XSLT processor The big difference to Cascading Stylesheets is that XSL transformations do more than just adding formatting properties XSLTs use XPath to access elements and subtrees of the source document but they never change the source Instead the output of the transfor mation is directed to a destination file The destination document can be XML formatted http en wikipedia org wiki Functional_programming 2 3 XSLT 16 but does not have to In most cases after a transformation some of the information is lost but it is also possible that after an XSL transformation information is added to the output Therefore transfor mations are not reversible in general An XSLT proc
43. d William Bradford Shockley who were awarded the Nobel Prize in physics in 1956 Ironically they had set out to manufacture a field effect transistor FET predicted by Julius Edgar Lilienfeld as early as 1925 but eventually discovered current amplification in the point contact transistor that subsequently evolved to become the bipolar junction transistor BJT 1 3 Types Figure 5 14 An editable PDF document 76 Chapter 6 Conclusions The final chapter gives an overview of the issues included in this document and covers some impressions the author gained during his work on this thesis 6 1 General Aspects The introduction of XML can have a very positive effect on a company s docu mentation process However as with any application XML does not by itself offer a key for a successful technical documentation It is only a standard on which so lutions can be built The basis of these solutions will only be realized when along with leveraging XML technology in its different forms the challenges currently being faced are taken into consideration 30 One of the main advantages is the separation of content structure and layout this enables a clear assignment to the corresponding authoring maintenance and pub lishing persons in charge An easier content creation process in association with the automated layout and conversion into multiple formats is leading to a faster process and additionally can save costs Furt
44. d are willing to make to choose the right approach 4 2 Single Sourcing Over the last years one term has caused a sensation among technical writers Sin gle Sourcing The reason is the enormous amount of text and image material that builds up in documentation throughout all companies So what s the big deal about single sourcing Kurt Ament provides a good answer to this question in his book 23 Single sourcing is a documentation method that enables you to reuse the information that you develop You build modular information then assemble that information into different formats Reusing in formation saves you time and money because it eliminates duplicate work Single sourcing also increases the usability of your documentation By developing modular information that is usable in any format you raise your documentation standards Usability standards that are nice to have in traditional documents become must haves in modular documents In effect single sourcing forces you to do the right thing for your users However it is very important that single sourcing has to be seen as a methodology It is not a technology that can simply be used on technical documents Kurt Ament points this out Single sourcing is a methodology not a technology Although the software tools associated with single sourcing are complex it is mod ular writing not technology that ultimately determines the success of single sourcing pro
45. d today at Infineon Technologies Then I started to work out the advantages and disadvantages of the current use of FrameMaker in combination with its XML capabilities Afterwards I started to design and implement a show case that enables technical documentation on a pure XML basis The Infineon internal process of finding an appropriate Enterprise Content Management Sys tem ECMS is not completed yet Therefore the showcases editing environment uses a file system based solution but can be easily connected to an XML based Content Management System in the future The chapters and their content have been organized according to the steps that were taken during the work Chapter 2 contains an introduction to XML as well as the explanations on other technologies used during the work on my thesis Chapter 3 gives an overview of the situation I met when I started my work at Infineon Technologies Chapter 4 contains a look out to what is possible with an XML based technical documentation Additionally a general insight to what open standards of which XML is one representative may be used for in the future will be given Chapter 5 explains what the showcase I implemented is capable of Chapter 6 gives a summary and a conclusion on the treated subjects Chapter 2 Used Technologies This chapter contains a short introduction to all technologies I used during the development of my Diploma Thesis If the reader is already familiar with XML and its
46. direct way to condition the text of a cross reference based on whether or not the target of the reference occurs on the same page as the reference itself There are no extensions that satisfy this requirement e Any other presentation tuning semantics that require feedback from the pag ination step to the initial FO generation step But note that this feedback could be provided in implementation specific ways enabling a multi pass process in which second and subsequent FO generation instances would have access to information about what page a given input node occurred on in the previous pagination instance None of the current products provide this feature e Dynamic page sensitive information in figure captions table captions and table headers although this can be faked using floats or tricks with page headers or footers in some cases Epic Publisher provides an extension for before floats that can be used to satisfy this requirement e Composition of back of the book indexes such that lists of page number citations are reduced to unique page numbers as well as the automatic cre ation of page ranges e Rotation of flowed text at angles other than multiples of 90 degrees The FO specification only provides for rotation in increments of 90 degrees There are no extensions for other rotation options However embedded SVG can be used with FOP and XSL Formatter to create a wide range of text effects e Creation of PDF bookmarks links and
47. dopt ebXML infrastructure e Realizing the commitment by ebXML participants to implement the ebXML tech nical specifications lwww ebxml org 4 1 XML BASED TECHNICAL DOCUMENTATION 36 ebXML was started in 1999 as an initiative of OASIS and the United Nations agency CEFACT The original project envisioned and delivered five layers of substantive data specification including XML standards for e Business processes e Core data components e Collaboration protocol agreements e Messaging e Registries and repositories 4 1 8 2 An Electronic Business Scenario The following example should help to illustrate the key benefits of ebXML as Benoit Marchal described it in his article 22 ACME Manufacturing Coyote Industries Figure 4 1 An Electronic Business Scenario without ebXML according to 22 Figure 4 1 is an electronic business scenario without ebXML ACME Manufacturing and one of its largest supplier Coyote Industries want to implement an electronic relationship 4 1 XML BASED TECHNICAL DOCUMENTATION 37 The goal is to streamline ACME procurement reducing costs and increasing competitive ness Assume that business issues have been dealt with ACME wants to buy from Coyote they have agreed on terms and payments ACME and Coyote add an XML connector to their business management system such as SAP Sage or QuickBooks That sounds easy but in fact it is rather difficult There are many technical issues to be dealt
48. e true gt lt fo block font size 8pt gt lt fo basic link text align right color blue external destination SserverPath filePath gt edit source lt fo basic link gt lt Lo bleck gt esl sar lt fo table cell gt lt fo table row gt lt fo table body gt lt fo table gt lt fo bleck gt lt o block gt lt fo block gt lt xsl apply templates gt lt xsl with param name chapNo select Schapternumber gt lt xsl apply templates gt lt Eos E ow gt lt fo page sequence gt lt xsl for each gt lt xsl for each gt 2 T0 7T08L gt lt xsl template gt lt Section FHHFEEEEEEEEEEEEEETE 7 gt 88 lt xsl template match section gt lt xsl param name chapNo gt lt Harrer HH Section header ttHFHEFTEE gt lt fo block id id gt lt fo block font family Helvetica gt lt fo block font size 12pt font weight bold gt lt fo block keep with next within column always space before optimum 12pt space before minimum 12pt 0 8 space before maximum 12pt x 1 2 gt lt xsl value of select SchapNo gt lt xsl number count section format 1 gt amp x00a0 amp x00a0 lt xsl value of select title i gt lt torbleock gt lt fo block gt Zi zorblock gt lt forblock gt lt xsl apply templates gt lt
49. e rather complex and verbose One of XSLT 2 0 s requirements was that it must simplify grouping As a simple example below shows it is well on its way to meeting that goal lt cities gt lt city name milan country italy pop 5 gt lt city name paris country france pop 7 gt lt city name munich country germany pop 4 gt lt city name lyon country france pop 2 gt lt city name venice country italy pop 1 gt lt cities gt The goal is to group the cities by the country they are in To achieve this goal XSLT 1 0 needs a rather complicated work around that is very error prone The code with XSLT 2 0 would like this lt xsl for each group select cities city group by country gt lt row gt lt col gt lt xsl value of select country gt lt col gt lt col gt lt xsl value of select current group name separator gt lt col gt lt col gt lt xsl value of select sum current group pop gt lt ol gt lt row gt lt xsl for each group gt 2 3 XSLT 18 In the above example lt xsl for each group gt initializes the current group as part of the XPath evaluation context The current group is simply a sequence Once the group is set up by using the group by attribute it can thereafter be referred to the current group using the current group function This completely eliminates th
50. e DTD quantifiers and that are also used in regular expressions In fact the RELAX NG compact syntax uses the very same quantifiers that are used in DTDs These very general quantifiers make it more difficult to state specific cardinality con 2 2 STRUCTURE OF XML DOCUMENTS 13 straints as with the XML Schema minOccurs and maxOccurs attributes can be done However it is possible and much easier to work around these limits using named patterns than it is to do so in DTDs Ordering multiple patterns is just a matter of listing the patterns in an order But a se quence of patterns at the same level can be given different semantics using the lt choice gt lt group gt or lt interleave gt elements The lt group gt tag is used in just the same way that parentheses are in DTDs By itself a lt group gt element does not mean anything but when used inside lt choice gt or lt interleave gt elements a group acts as one pattern rather than several The lt choice gt element expresses simple alternation between contained pat terns The lt interleave gt element provides the possibility to mix patterns while obeying the cardinality of each contained pattern For the sake of completeness the RELAX NG grammar of the example used in section 2 1 is listed below It shows that RELAX NG can get quite long winded even for such a small example due to the fact that it uses very few attributes lt xml version 1 0 gt
51. e considered FrameMaker is able to generate a DTD out of an EDD but there is one major drawback FrameMaker is able to im port a modular DTD but is not able to export a modular DTD as shown in figure 4 3 To be able to cope with that DTD EDD in the future it is necessary to split Element Definition Document EDD V lo ta zop Structure d Application Element Container Book Valid as the highest level element General rule Cover Revision_History BackCover Figure 4 3 FrameMaker is not capable of writing modular DTDs it up into smaller pieces For the current situation at Infineon Technologies there are two possible alternatives to achieve that The first one is a distributed DTD Which means every Business Unit BU has its own set of DTDs that fit their needs But they all agree upon one slim global DTD for technical documentation that consists only of a small set of elements that is necessary for document publishing Figure 4 4 pictures this approach In this case Business Unit specific information like registers or I O table data is converted with XSL transformations to normal tabular data before publishing the document Advantages of distributed DTDs e Each Business Unit has its own XML vocabulary e Only the most necessary elements are listed in the global DTD e Changes inside the XML vocabulary of a BU only concern the XSLTs of this Business Unit 4 1 XML BASED TECHNICAL DOCUMENTATION 42
52. e gt lt xsl apply templates gt lt xsl template gt Here the consecutively figure numbering is done and inserted below the actual figure together with the figure title lt figure title near figure gt lt xsl template match figtitle gt lt fo block id id gt fo inline gt Figure lt xsl number count figtitle format 1 gt lt fo inline gt lt fo inline gt lt xsl apply templates gt lt Fotvinilane gt lt forblock gt lt xsl template gt Cross references to figures are dissolved in this part of the code Therefore the appropriate figure number has to be found and afterwards inserted into the PDF 93 lt figure title as CrossRef Label gt lt xsl template match figtitle mode label gt Figure lt xsl number count figtitle format 1 gt lt xsl template gt lt xsl template match externalref gt lt fo basic link external destination link color blue lt xsl apply templates gt lt fo basic link gt lt xsl template gt lt xsl stylesheet gt page header footer xsl contains the header and footer information used for XSL FO files lt xml version 1 0 encoding ISO 8859 15 gt lt xsl stylesheet version 1 0 xmins xsl http www w3 org 1999 XSL Transform xmlns fo http www w3 org 1999 XSL Format gt lt xsl output omit x
53. e metal through hole plastic surface mount ball grid array lt item gt lt item gt Type BJT JFET IGFET MOSFET other types lt item gt lt item gt Polarity NPN N channel PNP P channel lt item gt lt item gt Maximum power rating low medium high_ lt item gt lt item gt Maximum frequency capability low medium high radio frequency RF microwave lt item gt lt item gt Application amplifier switch general purpose audio high voltage lt item gt lt list gt lt paragraph gt lt section gt lt chapter gt Back Figure 5 7 Content editing mode The user is able to call this function on any XML file stored inside the portal Afterwards the file is parsed and a web form is created that displays the markup of the XML file in a syntax highlighted manner with correct indention Only the 5 5 TABULAR EDITING 68 values of attributes and the elements content is replaced with text boxes contain ing the particular data With this technique it is not important if the user has any knowledge about the structural information of a XML file The user is now able to enter or edit content inside a XML document and does not have to take care of any markup data And by pressing the save button the changed data is stored directly into the XML file guaranteeing that the structural information is preserved One thing has to be taken in consideration the
54. e redundancy that was present in the XSLT 1 0 solution Note also the separator attribute on lt xsl value of gt The mere presence of this attribute instructs the processor to output not just the string value of the first member of the se quence but the string values of all members of the sequence in sequence order The value of the separator attribute is an optional string that is used as a delimiter between each string in the output For the sake of backward compatibility with XSLT 1 0 only the sequence s first member s string value is output when the separator attribute is not present Finally lt xsl for each group gt is able to solve different kinds of grouping problems de pending on which one of the three attributes is chosen e group by which has been used in the example above e group adjacent which enables grouping based on adjacency of nodes in document order e group starting with which groups by patterns of elements in a sequence Multiple output documents The second XSLT 2 0 feature that simplifies the writing of XSL Stylesheets is its support for creating multiple XSLT outputs This feature allows the definition of multiple XSLT transformation outputs in one XSL stylesheet In many real world applications the need to create multiple outputs from one XML document is given For example when creating an HTML report there could also be several Scalable Vector Graphics SVG Cascading Style Sheets CSS or metadata
55. ecause it means that software can decode it More specifically the CPP contains e the organization s name and contact information e the transport and security protocols it recognizes e the messaging protocols it recognizes 4 1 XML BASED TECHNICAL DOCUMENTATION 39 e the business processes and therefore ultimately the XML schemas that the orga nization recognizes e all kind of technical information such as URLs time out certificates and more that are necessary to setup an ebXML relationship Since the CPP describes all the capabilities of an organization it tends to be a fairly long document 20 pages or more The CPP is written in XML and follows very strict con ventions The XML snippet below is a tiny excerpt from Coyote s CPP This excerpt deals with the transport protocols that an organization supports It contains two tp Transport ele ments to indicate that the organization accepts messages either via Hyper Text Transfer Protocol HTTP or via Simple Mail Transfer Protocol SMTP lt tp Transport tp transportId http_connection gt lt tp TransportReceiver gt lt tp TransportProtocol tp version 1 1 gt HTTP lt tp TransportProtocol gt lt tp Endpoint tp uri https www coyote com ebxml tp type allPurpose gt lt tp TransportServerSecurity gt lt tp TransportSecurityProtocol tp version 3 0 gt SSL lt tp TransportSecurityProtocol gt lt tp ServerCertificateRef
56. ect2 gt lt title gt Types lt title gt lt paragraph gt Broadly speaking transistors are categorised as follows lt list gt lt item gt Semiconductor material germanium silicon gallium arsenide lt item gt Back Figure 5 5 Viewing mode of a XML file 5 3 Online Editing To enable XML based technical documentation on a web application the possibil ity to edit content online has to be provided This sounds easy but in fact it is not because of the limited capabilities web browsers offer to enter information The first idea was to provide a editing mode with syntax highlighting for XML Some research on this topic has been made throughout the design phase of this show case Online XML editing is not that common yet therefore only a small number of tools supporting such a functionality is available The decision was made to try a java script based open source program called helene Ihttp helene muze nl 5 4 CONTENT EDITING 66 But after a short time of testing it turned out that the performance with large XML files was too bad to work with that tool efficiently This was the reason to switch back to a normal text box based editing mode without syntax highlighting as shown in figure 5 6 Infineon technologies SPIX Showcase Portal for Improved XML TechDoc Home lt xml version 1 0 encoding IS0 8859 15 gt Upload lt chapter id chi gt lt title gt Developm
57. ed the fewest parameters Bear in mind that the CPP lists every possible option including which XML schemas to use through the business process A complete CPP is a very long document Still one question remains it all sounds great but what if the ACME s CPP is incompatible with Coyote Say ACME supports FTP only As we have seen Coyote does not support FTP Should that happen it means that two parties can not establish an electronic relationship At least one of the two must upgrade its system to make it compatible with the other Unfortunately software is not ca pable of generating relationships out of nowhere This has always been a major problem long before ebXML and will remain so even after ebXML 4 1 9 Modular DTD As we have seen in the previous sections XML in technical documentation pro vides some great advantages But there are also some dangers you can easily run into if you haven t planned your actions very well If you plan to use just a sin gle DTD to describe your XML vocabulary be aware of the fact that this DTD can become quite unhandy the more elements you define That is what happened with the DTD respectively EDD as described in section 3 2 the size of the EDD increased very fast over the time And today the EDD used at Infineon Technolo gies for technical documentation is so huge that it gets hard to maintain and work with it at all 4 1 XML BASED TECHNICAL DOCUMENTATION 4 Besides that one fact has to b
58. elements containing text but reading the first empty element it would behave in a greedy way and treat the empty element as if it were a text element Due to the fact that the empty element does not contain any text it does not match with the first declaration of elem and the validator would abort On the contrary RELAX NG would be able to solve that problem without much com plexity The declaration of the elements would look like this lt element name doc gt lt oneOrMore gt lt element name elem gt lt text gt lt element gt lt oneOrMore gt lt oneOrMore gt lt element name elem gt lt empty gt lt element gt lt oneOrMore gt lt element gt The semantics of RELAX NG are very straightforward in this respect they are a nat ural extension of DTD semantics 12 What a RELAX NG schema describes is patterns that consist of quantifications orderings and alternations In addition RELAX NG intro duces a pattern for unordered collection which neither DTDs nor XML Schemas support Moreover RELAX NG treats elements and attributes in an almost uniform manner Ele ment and attribute uniformity corresponds much better with the conceptual space of XML than does the rigid separation in both DTDs and XML Schemas The quantifications available to RELAX NG are identical to those in DTDs Any pattern may be conditioned as lt oneOrMore gt lt zeroOrMore gt or lt optional gt These corre spond to th
59. emiconductor device which can be used for amplification switching voltage stabilisation signal modulation and many other functions It acts as a variable valve which based on its input current BJT or input voltage FET allows a precise amount of current to flow through it from the circuit s voltage supply In essence it has three terminals Figure 1 A current or voltage applied through across two terminals controls a larger current through the other terminal and the common terminal In analog circuits transistors are used in amplifiers Analog circuits include audio amplifiers stabilised power supplies and radio frequency amplifiers In digital circuits transistors function essentially as electrical switches Digital circuits include logic gates RAM random access memory and microprocessors Transistor was also the common name in the sixties for a transistor radio a portable radio that used transistors rather than vacuum tubes as its active electronic components Figure 1 Transistors tape measure marked in centimeters 1 2 Invention The transistor was invented at Bell Telephone Laboratories in December 1947 first demonstrated on December 23 by John Bardeen Walter Houser Brattain and William Bradford Shockley who were awarded the Nobel Prize in physics in 1956 Ironically they had set out to manufacture a field effect transistor FET predicted by Julius Edgar Lilienfeld as early as 1925 but eventually discovered current amp
60. ent of the Transistor lt title gt lt section id sectO gt lt title gt Transistor lt title gt lt paragraph gt The transistor is a solid state semiconductor device which can be 1 lt paragraph gt lt paragraph gt In essence it has three terminals lt crossRef Idref CEGHDIBB type FigureTitle lt paragraph gt lt paragraph gt Transistor was also the common name in the sixties for a transistor radio a portal lt figure gt lt image file http localhost showcase db ITs20BT content transistor image lt paragraph gt lt section gt lt section id secti gt lt title gt Invention lt title gt lt paragraph gt The transistor was invented at Bell Telephone Laboratories in December 1947 first lt paragraph gt lt section gt lt section id sect2 gt lt title gt Types lt title gt lt paragraph gt Broadly speaking transistors are categorised as follows lt list gt lt item gt Semiconductor material germanium silicon gallium arsenide lt item gt lt item gt Physical packaging through hole metal through hole plastic surface mount lt item gt Type BJT JFET IGFET MOSFET other types lt item gt lt item gt Polarity NPN N channel PNP P channel lt item gt lt item gt Maximum power rating low medium high lt item gt x gt 4 Save Back Figure 5 6 Online editing mode 5 4 Content Editing To provide other forms of XML editing the im
61. ents are currently not fulfilled in XSL FO e Multiple independent multi page flowed areas within a single page body for example two independent articles on the same page that continue to different pages There are no known proprietary extensions for satisfying this requirement e Text that flows around arbitrary curved areas but text flowing around rec tangular areas is possible using side floats There are no extensions that 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 58 Vendor Product Remarks 3B2 3B2 FO available on multiple operat ing systems www 3b2 com Antenna House XSL Formatter conforms to XSL FO v1 0 W3C Recommendation www antennahouse com Apache project FOP open source java based xml apache org Arbortext Epic Editor generates PDF and PostScript www arbortext com Chive Products Apoc XSL FO NET integration www chive com IBM www alphaworks ibm com tech xfc XSL Format ting Objects Composer partial implementation of XSL FO v1 0 W3C Recom mendation RenderX www renderx com XEP Rendering Engine java based supports a subset of SVG XyEnterprise www xyenterprise com XPP available on multiple operat ing systems Table 4 1 Several available FO rendering engines 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 59 satisfy this requirement e Page location sensitive inclusion or exclusion of content For example there is no
62. essor needs at least two documents 1 the source document which has to be well formed XML at least 2 and a stylesheet which inherits the transformation instructions Afterwards the output stream contains the transformed document Figure 2 2 pictures the workflow of an XSL transformation Here only some possible output formats are displayed and some binary formats like PDF also require an additional rendering step after the XSL transformation However a complete description of possible output formats and how they are generated will be covered in section 4 3 PDF m gt _ Figure 2 2 The workflow of an XSL transformation 2 3 XSLT 17 2 3 1 XSLT 1 0 vs XSLT 2 0 In November 1999 XSLT version 1 0 became a W3C recommendation As is true with the first versions of many languages it did not become clear which extensions to the language would prove to be the most important until there had been some real world ex perience with it 15 XSLT in its version 1 0 has some major limitations Therefore five new features in XSLT 2 0 will be described here that will help to overcome those limitations 16 Grouping It is a common operation when transforming XML documents in XSLT to group data Especially to manage the tabular data from database tables and to publish them on the Web XSLT 1 0 did not include built in support for grouping Many grouping problems certainly can be solved using various techniques but such solutions tend to b
63. etica font size 12pt gt amp x2022 lt fo block gt lt f fo list item label gt lt fo list item body start indent body start gt lt fo block font family Helvetica font size 10pt gt lt xsl apply templates gt 90 lt forblock gt lt o list item body gt lt fo list item gt lt xslsfor each gt lt forlist block gt lt xsl template gt lt Table printing gt lt xsl template match table gt lt fo table border yes padding 2mm border width 0 3mm border style none table layout auto width 100 gt lt No of Columns gt lt xsl for each select thead row cell gt lt xsl if test position last gt lt fo table column column width width border right width 0 3mm border right style solid gt lt xsliif gt lt xsl if test position last gt lt fo table column column width width gt xs line gt lt xsl for each gt lt xsl apply templates gt lt fo table gt lt xsl template gt lt xsl template match thead gt lt fo table header font weight 900 gt lt xsl apply templates gt lt fo table header gt lt xsl template gt 91 lt xsl template match tbody gt lt fo table body wrap option no wrap gt lt xsl apply templates gt lt fo table body gt lt xsl template gt lt xsl template match row
64. f XPath 2 0 to de fine the result in the select attribute of the lt xsl result gt element As XPath 2 0 includes the ability to do conditional expressions if then and iterative expressions for return In general it has to be considered that XSLT 2 0 goes hand in hand with XPath 2 0 The two languages are specified separately and have separate requirements documents only because XPath 2 0 is also meant to be used in contexts other than XSLT such as XQuery 1 0 But for the purposes of XSLT users the two are linked together It is not possible to use XPath 2 0 with XSLT 1 0 or XPath 1 0 with XSLT 2 0 2 4 XSL FO This section covers XSL Formatting Objects XSL FO It is a complete XML application for describing the precise layout of text on a page It has elements that represent pages blocks of text on the pages graphics horizontal rules and more Most of the time how ever XSL FO is not written directly Instead an XSLT stylesheet that transforms your document s native markup into XSL FO is written The application rendering the doc ument reads the XSL FO and displays it to the user Since no major browser currently supports direct rendering of XSL FO documents there is normally a third step in which 2 4 XSL FO 21 another processor transforms the XSL FO into a third format such as PDF An XSL FO document describes the layout as a series of nested boxes or areas that are placed on one or more pages These boxes contain tex
65. files created for the report Since XSLT 1 0 does not have the capability to define multiple outputs in one XSL stylesheet there have to be separate XSLT transformations applied for each one Al though it is possible to write one XSL stylesheet that relies on XSLT parameters to indi cate which output to create the XSL stylesheet needs to execute multiple times and can be quite complicated because of the need to manage these parameters To simplify these kind of operations XSLT 1 0 processors provide various extensions to solve the problem However these extensions in XSL Stylesheets prevent them from being portable across processors In XSLT 2 0 a new lt xsl result document gt element can be used to define multiple outputs Generally two steps are required when defining multiple outputs 2 3 XSLT 19 e Setting up the output formats e Specifying the output file names Because each output might have a different format there have to be named output for mats defined using lt xsl output gt at the top of the XSL stylesheet Afterwards each lt xsl result document gt element generates the output format named by its attribute for mat lt xsl output method xml indent yes name xml format gt It is used later by lt xsl result document gt to create one XML document In addition to specifying the output format you can specify expressions defining the output file names In the example the output files are named usin
66. g a number by calling the position func tion lt xsl result document href output result_ position xml format xml format gt Temporary Trees Another new construct introduced in XSLT 2 0 are Temporary Trees Instead of representing the intermediate XSL transformation results and XSL variables as strings as in XSLT 1 0 the intermediate results and XSL variables constructed by lt xsl variable gt lt xsl param gt or lt xsl with param gt elements are stored as a set of docu ment nodes called temporary trees With temporary trees it is possible to evaluate the content of a variable or a parameter using the XPath expressions and modularize the XSL processing This approach offers a lot of flexibility when applying templates or extracting data from XSL variables or para meters It also improves the possibility to break up complex transformations into several modules and apply iterative processing on the XML documents Data type bindings Another simplifying feature is data type binding which is especially useful when using different types of data such as dates durations numbers and other XML schema data types In XSLT 1 0 data operations are limited to string number and boolean processing In XSLT 2 0 a stylesheet can use the 44 built in XML Schema data types and it is possible to construct functions associated with those data types Data types can be specified for all the variables or parameters defined by
67. her approaches may seem subtle but aDTD or XML Schema element definition tries to give a description of the element itself When RELAX NG defines the 2 3 XSLT 15 same element a pattern is defined that is checked against elements in the instance doc ument to see if they match much as if it were a regular expression being used to match text 13 The difference seems to be tiny on the surface but the pattern approach gives far more flexibility to write maintain and combine schemas 2 3 XSLT It turns out to be that the eXtensible Stylesheet Language Transformation XSLT is one of the most important standards beside XML Due to the fact that XML is often used as a data interchange format it is important to have a universal efficient method at hand that is capable of converting XML documents With XSLTs it is very easy to transform XML documents between different structural models but it is also possible to generate other formats like LaTeX or plain text out of XML XSLT is a programming language that has been developed especially for transformation of XML documents and because of that it is the better choice than general purpose lan guages like C or Java in most cases For some developers XSLT will seem rather different to normal programming languages because it is based on the concept of functional pro gramming Good XSLT programming will need a rethinking on design and programming methodology therefore it is an important aspect to
68. here are no rendering engines or compilers needed So with the help of XSLTs you can easily convert your XML documents to HTML Figure 4 8 pictures this workflow The main advantage of HTML is that with the quick growth of the World Wide Web WWW it is available almost everywhere and on any possible architecture or operating system Therefore with the help of XSLT you have the possibility to provide your latest information to the web directly out of your XML data basis With the further development of browser technology in the near future even the step of XSL transformation will no longer be necessary because the browsers will be able to present XML information directly of course with the support of style information it will always look better Another convenience of the direct transformation from XML to HTML is the fact that you can use it as some sort of preview for the information you are creating As mentioned in section 4 3 XML structured information brings an advantage to the writer but it is not that easy to read As a writer you have to re read your writing from time to time and to do this an HTML preview really is a great ease 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 52 XML lt markup text data lt chapter gt lt title gt Computer History lt title gt lt paragraph gt In 1950 lt paragraph gt lt chapter gt HTML markup text data lt h1 gt Computer History lt h1 g
69. hermore using XML to semantically markup documents guarantees the reuse of the information stored inside The discussion with authors and other responsibles working in technical docu mentation has been proven to be the most important basis for gathering informa tion and requirements Only after analyzing the requirements and considering the current problems of technical documentation the showcase could be built in a way that it offers new improved possibilities in technical documentation 6 2 PERSONAL IMPRESSIONS 41 XSLT and XSL FO turned out to be very effective technologies for use in techni cal documentation XSL transformations provide good flexibility and full control over the conversion of XML documents to other formats Formatting Objects al ready is a good starting point for layout driven formatting and when some of the limitations are overcome with further development it will become even more im portant The decision to implement this showcase as a web application was not an easy one there were some difficulties that could not be overcome like the syntax high lighting in editing mode However in the long run the advantages will outweigh the disadvantages and although this showcase is far away from being a compet itive product it fulfilled its needs and gave a good impression of how technical documentation could be done in the near future 6 2 Personal Impressions Working in a company that is one of the global players
70. hnical authors and document managers take care of authoring editing quality management layout and publishing At Infineon Technologies the standard tool for writ ing technical documents at the moment is Adobe FrameMaker FM in the current version 7 1 Besides FrameMaker other Microsoft Office Products like Word or Excel are also in use At present the documentation is being created using different applications and is stored in various proprietary formats for instance as FrameMaker or Microsoft Office files Those files are stored in different systems and databases Nearly all documents are managed and versioned manually using a directory structure on file servers or local hard disks As a result there are sometimes several documents bearing the same name at vari ous places Management of reusable text parts is mostly done manually using functionalities of the word processing software to support it if possible This means for instance that if a new document version is released and parts of it are being used in other documents the author has to remember this and effect the changes If the documents are published in other data formats he also has to redo the data conversion processes as well Documents have to be collected manually in order to publish them on the Internet The conversion to the different data formats for electronic publishing has to be initiated by hand too There are several problems with Adobe FrameMaker when it is used for
71. igure 4 9 Workflow to convert XML to CHM 3http msdn microsoft com library default asp url library en us htmlhelp html vsconHHlStart asp 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 54 Nevertheless XML can be easily transformed to HTML and the step to compile HTML files to CHM can be automated And because of the fact that Microsoft Windows and its help files are widely used the possibility to transform technical documentation to CHM should always be considered To give a small impression figure 4 10 shows how HTML Help looks like E windows 2000 aT gt E Ausblenden Zur ck Vorw rts Optionen Webhilfe Inhalt Index Suchen Favoriten Start Einf hrung in Windows 2000 Professional Dateien und Ordner Internet E Mail und Kommunikation Arbeiten mit Programmen Individuelle Einrichtung des Computers Hardware Drucken Problembehandlung und Verwaltung Netzwerke Eingabehilfen f r besondere Anforderunger Mobile Benutzer windows 2000 Supporttools Windows 2000 stellt zahlreiche Supporttools f r Systemadministratoren und Supportmitarbeiter zum Erkennen und L sen von Computerproblemen zur Verf gung Viele dieser Supporttools sind im Betriebssystem enthalten und k nnen von der Hilfe aus ge ffnet werden Zus tzliche Tools k nnen von der Windows 2000 CD gedownloadet werden Klicken Sie auf eine der folgenden Optionen um Informationen ber h ufig verwendete Tools zu erhalten
72. include audio amplifiers stabilised power supplies and radio frequency amplifiers In digital circuits transistors function essentially as electrical switches Digital circuits include logic gates RAM random access memory and microprocessors lt paragraph gt lt paragraph gt Transistor was also the common name in the sixties for a transistor radio a portable radio that used transistors rather than vacuum tubes as its active electronic components lt figure gt lt image file http localhost showcase db IT 20BT content transistor images trans jpg height 100pt width 216pt position below sideways 0 impang 0 000 nsoffset 0 000in gt lt figtitle id CEGHDIBB gt Transistors tape measure marked in centimeters lt figtitle gt lt figure gt lt paragraph gt lt section gt lt section id sect1 gt lt title gt Invention lt title gt lt paragraph gt The transistor was invented at Bell Telephone Laboratories in December 1947 first demonstrated on December 23 by John Bardeen Walter Houser Brattain and William Bradford Shockley who were awarded the Nobel Prize in physics in 1956 Ironically they had set out to manufacture a field effect transistor FET predicted by Julius Edgar Lilienfeld as early as 1925 but eventually discovered current amplification in the point contact transistor that subsequently evolved to become the bipolar junction transistor BJT lt paragraph gt lt section gt lt section id s
73. item gt Application amplifier high voltage lt item gt lt lisE gt lt paragraph gt lt section gt lt chapter gt ch2 xml second chapter lt xml version 1 0 encoding lt chapter id ch2 gt lt title gt FET Families lt title gt lt paragraph gt frequency RF microwave lt item gt switch general purpose audio 150 8599 15 3 gt FETs are divided into two families junction FET JFET and insulated gate FET IGFET also known as metal oxide silicon or semiconductor FET MOSFET Unlike IGFETs the JFET gate terminal forms a diode with the channel semiconductor material 81 between source and drain Functionally this makes the N channel JFET the solid state equivalent of the vacuum tube triode which similarly forms a diode between its grid and cathode Also both devices operate in the depletion mode they both have a high input impedance and they both conduct current under the control of an input voltage lt paragraph gt lt paragraph gt FETs are further divided into enhancement mode and depletion mode types Mode refers to the polarity of the gate voltage with respect to the source when the device is used for linear amplification Taking N channel FETs in depletion mode the gate is negative with respect to the source while in enhancement mode the gate is positive For both modes if the gate
74. ity is enabled It would also be possible to pass this information in as a stylesheet parameter for more flexibility lt Global Variables tHHH HTH ETE ETT gt lt xsl variable name serverPath select http localhost showcase editxml aspx file db it bt content transister gt lt gt lt xsl template match gt lt LIo 2OoE gt lt The lt fo layout master set gt element contains one or more page templates gt lt fo layout master set gt lt Bach lt fo simple page master gt element contains a single page template Each template must have a unique name master name gt lt fo simple page master master name A4 page width 210mm page height 297mm margin top Icm margin bottom lcm margin left 2cm margin right 2cm gt lt fo region body margin top 2 4cm margin bottom 2cm gt lt fo region before region name xsl region before extent 2 4cm display align before gt lt fo region after region name xsl region after extent Dem J gt lt fo region start extent 1 5cm gt lt fo region end extent 1 5cm gt lt fo simple page master gt lt fo layout master set gt lt One or more lt fo page sequence gt elements describe page contents The master reference attribute refers to the simple page master template with the same name gt 84 The code below generates the table of conten
75. ived from discussions with authors docu ment managers and team members 4 1 XML based Technical Documentation The explosion of content and the need to manage mine and obtain information in a quick and efficient way is nowadays more important than ever before Therefore the advantages of an XML based solution for technical documentation are described in the next sections 4 1 1 Standardization Standardization in information representation and transfer is crucial XML is a platform and application independent and vendor neutral mechanism XML relies on other tech nologies in particular SGML for syntax URIs for name identifiers and Unicode for character encoding which are all standards This high grade of standardization provides a solid basis to use this technology in the field of technical documentation 4 1 2 Manageability The advantage of data being independent of any particular platform application or ven dor is that it can be transformed to produce different types of outputs for different media devices as for instance paper CD ROM or a web browser without the need to modify the original content 4 1 XML BASED TECHNICAL DOCUMENTATION 33 When modifications are required only the original version of the content needs to be edited before republishing to the various target media This leads to efficiency and easy maintainability without the inherent problems of version control and the effort required in making modifications i
76. jects To ensure success develop local project based standards for modular writing Base your standards on what actually works in your own projects The key features to do successful single sourcing in technical documentation are examined throughout the next sections 4 2 SINGLE SOURCING 45 4 2 1 Conditions When using the single sourcing method concentrate on content and not on for mat Therefore content based documentation is very different from format based documentation which is written only for a particular document format and is de signed to be read in a predefined sequence So there are several things that have to be considered Format based content is not reusable In traditional documentation individual documents are hand crafted for a particular output format only for example e Printed manual e Online help e Website But the content is always tied to the format and cannot be reused easily Reuse of this type of documents always requires extensive rewriting Content based content is reusable To take advantage of the re usability separation of content from format has to be done when developing information To achieve this a technology like XML is the ideal solution furthermore it enables the development informa tion on an element level rather than a document level e Document level linear e Element level modular Linear writing is not reusable Linear writing assumes a given reading sequence It is inte
77. l ebXML An Electronic Business Scenario July 2003 www developer com xml print php 2234201 2005 05 28 Kurt Ament Single Sourcing Building Modular Documentation Noyes Publications September 2002 Rebecca Sukach Robert Kennedy and Marie Devine Implementing Single Sourcing in Your Organization www stc org confproceed 2002 PDFs STC49 00032 pdf 2005 05 28 Cherryleaf Ltd Cherryleaf survey results Use of single sourcing solutions April 2003 www cherryleaf com singlesourcessurvey htm 2005 05 28 James Clark Document Style Semantics and Specification Language www jclark com dsssl 2005 05 28 Jan Goyvaerts How to Create HTML Help Files with HelpScribble April 2004 www helpscribble com htmlhelp html 2005 05 28 Kimber W Eliot Using XSL Formatting Objects for Production Quality Document Printing December 2002 BIBLIOGRAPHY 101 29 30 www idealliance org papers xml02 dx_xm102 papers 06 05 01 06 05 01 pdf 2005 05 28 Ben Shneiderman Treemaps for space constrained visualization of hierarchies December 1998 www cs umd edu hcil treemap history index shtml 2005 05 28 C Y Hsieh File Design for Information Systems pluto ksi edu cyh cis501 ch8 html 2005 05 28
78. lification in the point contact transistor that subsequently evolved to become the bipolar junction transistor BJT 1 3 Types Figure 5 12 Final book pdf generated completely out of XML data in a document it is possible to jump directly to the source that is behind that doc ument and by changing that source all documents that derive from that source also inherit the changes after the transformation to the desired output format is reprocessed To activate the edit source links the stylesheet parameter editsource has to be set to true before the XSL transformation is started How this must look like is pictured in figure 5 13 The result after the transformation is done and the rendering is completed can be seen in figure 5 14 Now there is a edit source link beside each chapter head ing by clicking on one of those links the according XML component is opened in 5 7 PDF GENERATION 74 Infineon SPIX Showcase Portal for Improved XML TechDoc Home Perform Transformation on book xml Upload Choose XSLT file Enter XSL Params e g date 10 01 2005 lang de Output filename combine2fo xsl DJ 8 combine2htmil xsl combine2xml xsl readme2fo xsl c E utp2myXML xsl book2fo xsl Back editsource true book fo Figure 5 13 Activate the edit source functionality the online editing mode inside the portal With a single click it is now possible t
79. matting program a so called Formatting Objects Processor FOP or more generally a rendering engine This workflow is pictured in figure 4 12 4 3 4 1 Rendering Engines XSL FO engines unfortunately either come as open source programs or feature rich products for purchase but not both at the same time There are several pro grams listed in table 4 1 that provide XSL FO rendering some of them comply very well with the XSL FO W3C Recommendation others do not They also dif fer in the set of features they provide Therefore an evaluation of available FO processors is recommended based on the initial situation and the requirements the engine has to fulfill In the showcase provided with this thesis an evaluation version of the Apoc XSL FO processor from Chive Software has been used due to the fact that it supports a good NET integration 4 3 4 2 Limitations of XSL FO Although XSL FO is able to satisfy almost all needs for publishing technical doc umentation there are certain limitations that cannot be overcome with the current Formatting Objects vocabulary In fact some rendering engine implementations like the Epic Editor from Arbortext provide extensions to remove some of the boundaries of XSL FO Eliot Kimber of ISOGEN offers a detailed paper about the drawbacks of using XSL FO for technical documentation some of the most important limitations are listed here for the full list please refer to his paper 28 The following requirem
80. ml declaration no method xml encoding UTF 8 indent yes gt lt Draw the Page header HH HH gt lt xsl template name draw page header gt lt fo static content flow name xsl region before gt lt fo block text align start gt lt fo external graphic src http localhost showcase db IT 20BT content wg images logo_infineon bmp width 122px height 57px gt 94 lt fo block gt lt fo block font family Helvetica margin left 123px gt lt fo table table layout fixed width 80 gt lt fo table column column number 1 column width 80pt gt lt fo table column column number 2 column width 400pt gt lt fo table body gt lt fo table row height 4pt gt lt fo table cell text align left display align before gt lt Eo block gt lt fo black gt lt ro bleck gt lt fo table cell gt lt fo table cell text align center display align before border bottom width 0 5pt border bottom style solid border bottom color black gt lt forblock gt lt for block gt lt fo block gt lt fo table cell gt lt fo table row gt lt fo table body gt lt fo table gt lt fo bleck gt lt fotstatie content gt lt xsl template gt lt Draw the Page Footer tHHTFEEEEEEEEETEETEEEEEEEEEEEEEE gt lt xsl template name draw page footer gt lt fo static content flo
81. n medium specific document versions This allows authors to concentrate on authoring rather than formatting and thus to be more productive 4 1 3 Longevity Proprietary binary formats only lasts as along as the systems which support it XML data exists as plain text This gives data a longer life span with future readability and reuse of data Even if a system becomes obsolete the data will live on and will remain accessible in the long term This is a very valuable attribute of the XML technology consider the support for a product like Adobe FrameMaker would stop the process described in section 3 2 would get in serious trouble 4 1 4 Extensibility XML provides a standard framework to create markup vocabularies that are business oriented and can easily be used to build a meta language for any kind of technical doc umentation Due to its complexity this was much more difficult with its predecessor Standard Generalized Markup Language SGML 4 1 5 Development XML is simpler than SGML and easier to implement This has the following practical advantages 1 One of the prime advantages of XML is that generic programs such as parsers can be developed that can be used with any XML vocabulary Even though the pro grams themselves could be platform dependent the XML documents themselves are plain text and therefore platform independent 2 A programmer can use tools from different vendors to process the same data With several choices
82. ncluding it can be said that as the development of XML started in 1996 it has been a long way until today Nevertheless XML has survived the hype cycle shown in 2 1 as predicted by the Gartner Research Group 3 However only the future can tell if other XML related technologies will also become as popular and sophisticated as XML is today Combining all these technologies and their usage I think we are standing at the start of the Slope of Enlightenment today when using XML for technical documentation 2 2 STRUCTURE OF XML DOCUMENTS 6 Visibility Key Time to Plateau XML Rendering WS Security XKMS ACORD O Less than two years SAML Two to five years XSLT Five to 10 years XBRL A More than 10 years UBL XSL XML Topic Map XRML PMML XML Appliances ebXML IFX As of May 2003 Technology Peak of Inflated Trough of Slope of Plateau of Trigger Expectations Disillusionment Enlightenment Productivity Maturity Acronym Key SOAP Simple Object Access Protocol ACORD Association for Cooperative Operations UBL Universal Business Language Research and Development WSDL Web Services Description Language CICA Context Inspired Component Architecture XBRL Extensible Business Reporting Language DBMS database management system XACML XML Access Control Markup Language IFX Interactive Financial Exchange XKMS XML Key Management Specification MISMO Mortgage Industry Standards XML A XML for Analysis Maintenance Orga
83. nd of element that describes pieces of information In order to use this feature a lot of work has to be done before you have to set up so called Application settings These settings include a document called Element Defi nition Document EDD and Read Write rules An EDD is similar to a DTD but un fortunately compromises the idea of separating content and layout and adds formatting information to the elements structure Another drawback of an EDD is that it is an Adobe proprietary format and therefore can only be accessed and edited when you open it with Adobe FrameMaker The major advantage of working with FrameMaker in structured mode is that it allows you to export your FM documents as XML documents In order to do such an XML export Read Write rules are needed to specify how element names are translated to tag names in XML Furthermore you need an EDD which ensures that elements are structured in a way they are allowed to similar to a DTD The screenshot in figure 3 2 shows how Adobe FrameMaker looks like in structured mode On the left side of the figure you can see the WYSIWYG window of the current docu ment In front is the structured view that represents the current document in a treeform and on the upper window all elements are listed that can be inserted at the current cursor position If FrameMaker is used as an authoring tool for a large group of people there are certainly some difficulties that could be avoided using a pu
84. nded to be read from beginning to end For instance in linear writing pieces of text like Jater in this chapter or earlier in this section would be found very often Obviously these references would not make much sense in an online help system All these sequence references would have to be removed and have to be rewritten to use the information in a modular way Therefore linear docu mentation is almost impossible to reuse 4 2 SINGLE SOURCING 46 Modular writing is reusable Modular writing is non sequential stand alone content modules that make sense on their own have to be written The idea is to chunk information based on the type of information being presented For example use descrip tive text to explain what a product is and use procedures to explain how to operate the product and flowcharts to illustrate product processes To assemble those chunks to a document use cross references to link each step to another When chunking and linking information in this way a de velopment of content that can easily be assembled into different documents is possible 4 2 2 Granularity of Structure Granularity of a documents structure is an important point to successful single sourcing although there cannot be a universally valid answer to the question what the best granularity for your document structure is That has to be defined for each case individually If a document structure is to fine and uses too much elements it
85. nization XQuery XML Query Language OWL Web Ontology Language XRML XML Rights Management Language PMML Predictive Model Markup Language XSL Extensible Stylesheet Language RDF Resource Description Framework XSLT Extensible Stylesheet Language Transformation SAML Security Assertion Markup Language Source Gartner Research May 2003 Figure 2 1 Hype Cycle for XML Technologies 2003 2 2 Structure of XML documents In the following two sections a short introduction of Document Type Definitions and Schemata will be given Some of the differences advantages and disadvan tages of these two technologies will be covered 2 2 STRUCTURE OF XML DOCUMENTS 7 2 2 1 Document Type Definition Document Type Definition DTD was part of the XML 1 0 recommendation A DTD is written in a formal syntax that explains precisely which elements appear where in the document and what the elements content and attributes are 4 With the help of XML different sets of tags markup languages can be de fined which are adapted to their intended fields of application XML documents can also be created without the definition of a document structure But DTDs are useful as they e serve to unify the structure of different kinds of documents used in a com pany e g user manuals or data sheets issued by various business groups e define a so called shared context Such a shared context is a formal de scription of the rules a metadata must f
86. nning The costs required to purchase implement and maintain the software to support the single sourcing are low com pared to the effort that has to be invested in teaching the technical writers Because first of all they have to learn the methodology of the single sourcing approach only 4 2 SINGLE SOURCING 48 x E C B F y D b lt ref link F gt lt ref link D gt XSLT 2 lt ref link A gt 1 assembly file formatted output file Figure 4 6 Example of an assembly file after that the software can support their work The concept of single sourcing promises reduced cost and increased quality By writing editing reviewing and localizing the information once and reusing it many times in different formats and forms production and maintenance costs drop significantly The quality of deliverables increases because the information content can be tailored to each format 24 Single sourcing can be a challenging transition but may not be the correct solution for every situation For a company like Infineon Technologies that manufactures so many products and to each product a significant number of technical documents has to be provided in my opinion it is an absolute must Although the advantages outweigh the drawbacks a survey made by Cherryleaf Ltd 25 in April 2003 shows in figure 4 7 that single sourcing i
87. nt CPA that describes how to establish the electronic relationship In essence the CPA is the answer to all the questions put forward in the first case What does the CPA have to include In most cases the choices are simple and can be au tomated For example if Coyote supports HTTPS or PGP but ACME supports S MIME and PGP the only practical option is PGP Some issues might not be so clean cut and would be reviewed by the operator installing the software ACME sends the CPA to Coy ote for validation If Coyote accepts it they are in business Step 3 and beyond is to exploit the business relationship The dotted line between Coy ote and the registry in figure 4 2 indicates that Coyote will update its CPP as it adds or removes capabilities E g if Coyote adds S MIME support it needs to say so in its CPP The fundamental difference between the two scenarios is that with ebXML the costly configuration is now automatic which means cheaper and faster Obviously there is another difference between the scenarios with and without ebXML If you can establish electronic relationships in minutes instead of weeks then you can afford to build many more of those To get a better understanding on how the interaction with the help of ebXML works a closer look on the Collaboration Protocol Profile CPP is taken The CPP is a formal description file that lists what an organization can do in terms of ebXML operations Formal is the operative word b
88. o jump to the source that lies behind the PDF document 5 7 PDF GENERATION 73 Ale BASE HR EM gt gt DON EB AR B08 Infineon technologies 1 Development of the Transistor 1 1 Transistor The transistor is a solid state semiconductor device which can be used for amplification switching voltage stabilisation signal modulation and many other functions It acts as a variable valve which based on its input current BJT or input voltage FET allows a precise amount of current to flow through it from the circuit s voltage supply In essence it has three terminals Figure 1 A current or voltage applied through across two terminals controls a larger current through the other terminal and the common terminal In analog circuits transistors are used in amplifiers Analog circuits include audio amplifiers stabilised power supplies and radio frequency amplifiers In digital circuits transistors function essentially as electrical switches Digital circuits include logic gates RAM random access memory and microprocessors Transistor was also the common name in the sixties for a transistor radio a portable radio that used transistors rather than vacuum tubes as its active electronic components Figure 1 Transistors tape measure marked in centimeters 1 2 Invention The transistor was invented at Bell Telephone Laboratories in December 1947 first demonstrated on December 23 by John Bardeen Walter Houser Brattain an
89. of XML processors already available it also frees the programmer from having to write parsers from scratch This allows the programmer to concen trate on other aspects of the application 3 XML is usually referred to as portable data in the sense that its parsing is appli cation independent and one XML parser can read every possible XML document 4 1 XML BASED TECHNICAL DOCUMENTATION 34 4 The time and effort used in set up of the programming environment libraries mod ules software can be used for different XML vocabularies 5 The skills attained in a project on one specific vocabulary is often transferable to others For example once having learned how to write XSLT style sheets for transformations this skill can be reused with any other XML vocabulary 4 1 6 Decoupling Structure and Presentation The vocabularies based on XML syntax can keep the structure of the content separate from its presentation This has long term advantages particular towards document maintenance and automated processing This is a major improvement over HTML which allowed the mixture of structure and presentation both implicitly and explicitly And especially in Technical Documentation this separation of structure and layout is a major benefit for example in generating different output formats from one content source This will be covered in detail in section 4 3 4 1 7 Human to Machine and Machine to Machine Interfaces XML provides both
90. ollow and serves as a contract be tween the document sender and the document receiver The sender agrees that the document conforms to the shared context The document receiver agrees to interpret the document according to the shared context 5 Unfortunately a DTD does not provide the following information about an XML document e What the root element of the document is e How many instances of an element are allowed in a document e What the data inside an element looks like for example is it a string a date a integer or real value or something completely different A DTD that defines the structure for the XML document that was introduced in section 2 1 would look like the listing below As you can see elements and at tribute lists are described in a formal syntax The first line declares a Book element and states that it must contain exactly one Title Author and Publish ingDate child element followed by one or more Chapter elements lt ELEMENT Book Title Author PublishingDate Chapter gt lt ELEMENT Title PCDATA gt lt ELEMENT Author PCDATA gt 2 2 STRUCTURE OF XML DOCUMENTS 8 lt ELEMENT PublishingDate PCDATA gt lt ELEMENT Chapter ChapterTitle Paragraph t gt lt ATTLIST Chapter ID ID REQUIRED gt lt ELEMENT ChapterTitle PCDATA gt lt ELEMENT Paragraph PCDATA gt lt ATTLIST Paragraph ID ID REQUIRED g
91. or MSXML that is integrated into the Net environment has been used Any concerns on the performance of server side transformations could not be confirmed The performance mainly de pends on the amount of data that has to be transferred between client and server 5 7 PDF GENERATION 71 5 7 PDF Generation PDF Generation is a two step process as already stated in section 4 3 4 During the first step a XSL transformation is applied to convert the XML document to a XSL FO compliant vocabulary In this example book xml displayed in figure 5 10 is used as an assembly file What an assembly file should look like and how it works can be read in section 4 2 4 When applying the XSL transformation on book xml it combines two XML components in this case chapter I and chapter II to a complete XSL FO book Infineon SPIX Showcase Portal for Improved XML TechDoc Home Upload lt xml version 1 0 encoding ISO 8859 15 gt lt book gt part link chapter chi xml gt part link chapter ch2 xml gt lt book gt Figure 5 10 Example of an assembly file In the second step this XSL FO file has to be rendered into a PDF Figure 5 11 shows a gen pdf button next to the book fo file that has been generated as a result of the XSL transformation By clicking on that button the processing engine is started and the file is rendered into a PDF document 5 7 PDF GENERATION 72 oo Infineon SPIX
92. plementation of a so called content editing mode was another goal This specific type of editing mode has two major advantages First of all it removes the annoying task of programming web forms 5 4 CONTENT EDITING 67 over and over again for each application only to allow the user to enter informa tion that is afterwards stored in a database or transformed into XML again The second advantage of content editing mode that figure 5 7 shows an example of is that the user can enter data directly into a XML document without being able to modify or even destroy the structure of the document Only the content itself is editable lt section id secti rok lt title gt lt title gt Invention The transistor was invented at Bell Telephone a Laboratories in December 1947 first demonstrated on December 23 by John Bardeen Walter Houser Brattain and William Bradford Shockley who were awarded the Nobel Prize in physics in 1956 Ironically they had set out to manufacture a field effect transistor FET lt paragraph gt predicted by Julius Edgar Lilienfeld as early as 1925 but x lt paragraph gt lt section gt lt section id sect2 es lt title gt Types _ lt title gt lt paragraph gt Broadiy speaking transistors are categorised as follows lt list gt lt item gt Semiconductor material germanium silicon gallium arsenide lt item gt lt item gt Physical packaging through hol
93. re XML authoring environment First of all if a group of authors should write their documents using the same set of tags FM application settings including an EDD and Read Write rules would have to be distributed to all of them by hand That means that an EDD cannot be referenced as simple as a DTD by providing an Universal Resource Identifier URI Furthermore a DTD can be extended easily and does not have to be reversioned as long as certain constraints are considered On the contrary if changes are made or something is extended in an EDD the Read Write rules have to be updated and the whole FM application settings have to be redistributed among all authors 3 2 THE CURRENT PROCESS IN TECHNICAL DOCUMENTATION 30 Adobe FrameMaker Structured Eile Edit Element Format View Special Graphics Table Window Help Ei H WG_FM7_XML_2004 06 14 fm Writers_guide fm Ze x Eodertogmori v CrossReference Infineon WG_FM 7 XML Dec v Deleted technalogies X Emphasis Footnote XML Basics v Hex Hyperlink v index yasiosmasasonanas aussage Serene re rerreeecennte reece ASAS EKAS A SEE AANDRA EEOAE RASAS EAEE ters Y ninan 2 L Basics v Inserted Theory and some useful links Negation 21 XML Advantages Main advantages XML documents and databases build one unit XML can easily be read by humans and by machines XML is becoming an international Standard Structure View x New development test equipment and Microsoft Office tool
94. re currently in use on the technical documentation process described above at Infineon Technologies e The Product Requirement Document PRD is based upon a first product idea It also contains information on all relevant items 3 2 THE CURRENT PROCESS IN TECHNICAL DOCUMENTATION 28 needed to evaluate a business opportunity This includes a product summary in formation on the market a system concept technical concept a financial plan customer involvement as well as information on the software and development tools e The Product Specification is being created based upon the information from the PRD This specification de scribes the entire system lists all relevant standards and test procedures e The Design Specification implements the information provided by the product specification This specifica tion defines the function of a chip for example its architecture and the divisioning between hardware and firmware features e The Device Description and Qualification Report The Device Description contains some information about the product the produc tion process its thermal characteristics and the amounts and types of packages it will be sold in Depending on the Business Unit Qualification Reports are either also part of the Device Description document or issued separately e The Product Brief is a marketing oriented document describing a product idea It is distributed to se lected potential customers and is used to ev
95. related technologies the next four sections can be skipped and it should be continued with section 2 5 2 1 XML The eXtensible Markup Language XML is a World Wide Web Consortium W3C standard for document markup 1 It is said to be the descendant of Hypertext Markup Language HTML but in fact it is a descendant and a simplification to the much more complex Standard Generalized Markup Language SGML which was also a recommendation of W3C back in 1986 2 XML defines a generic syntax used to mark up data with simple human readable tags It provides a standard format for computer documents that is flexible enough to be customized for areas as diverse as electronic data interchange vector graph ics object serialization to remote procedure calls and even more XML is a meta markup language for text documents Data in XML is included as strings of text The data is surrounded by text markup that describes the data XML s basic unit of data and markup is called an element The XML specification defines the exact syntax this markup must follow how elements are delimited by tags what a tag must look like what names are acceptable for elements where attributes are placed and so forth The markup in an XML document looks a lot 2 1 XML 4 like the markup in an HTML document but there are some crucial differences Most important XML is a meta markup language That means it does not have a fixed set of tags and elements Any attempt to
96. ructs it allows These control how programs and applications are built and how solutions are formed Language syntax is the form and style of a programming language This includes is sues such as where brackets are needed use of space and how constructs such as loops or control structures are formed By separating semantics and syntax NET allows an entire family of programming languages to share the same library functions the same web functionality and the same database access methodology Therefore all NET fam ily languages are built on top of the CLR The two most prominent NET languages are C and Visual Basic NET They share the same semantics but C has a syntax derived 2 5 ASP NET AND C 24 from C and shared with C and Java while Visual Basic has an alternative look and style C is a new language designed by Microsoft to combine the power of C C and the pro ductivity of Visual Basic Initial language specifications also reveal obvious similarities to Java including syntax strong web integration and automatic memory management So if you have programmed in either C or Java starting with C should be fairly straight forward 20 25 Chapter 3 The Present This diploma thesis has been written at the IT line for Business Transformations IT BT and its RDS Research amp Development Solutions department at the Infineon Technolo gies AG in Munich Infineon is a large enterprise in the international semiconductor
97. s a clean 5 2 FUNCTIONAL OVERVIEW 62 eo Infineon SPIX Showcase Portal for Improved XML TechDoc Home Upload GAI 18 03 2005 COM 18 03 2005 IT BT 18 03 2005 MP 18 03 2005 Figure 5 2 Division according to Business Units XML based environment It is recommended to use such a directory configura tion for efficient work with this showcase Directories described in detail e content contains only pure XML content modules e dtd contains all structural information describing the XML modules files in here can either be referenced by relative path or by URI e output contains all files that are generated as a result of XSL transformations e style contains all transformation files XSLTs together with Cascading Style Sheets CSS 5 2 FUNCTIONAL OVERVIEW 63 Infineon SPIX Showcase Portal for Improved XML TechDoc Home Upload a content 18 03 2005 dtd 18 03 2005 output 18 03 2005 style 18 03 2005 Figure 5 3 Directory structure for a XML based environment The main work will be done inside the content directory this is also where most of the functionality on XML files is carried out Figure 5 4 points this out Each of these feature will be treated throughout the next sections 5 2 FUNCTIONAL OVERVIEW 64 Infineon SPIX Showcase Portal for Improved XML TechDoc Home P Upload showcase_readme 18 03 2005 Owg 18 03 2005 transistor 10 04 2005 map xml 14
98. s not that widely used yet 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 49 No but we plan to Figure 4 7 Survey results Use of single sourcing solutions Response Percentage Yes We use a single sourcing authoring solution 35 9 No but we plan to in the next 12 months 11 9 No 48 5 Yes but we plan to stop doing so in the next 12 months 1 5 Don t know 2 2 4 3 Transformation to different Output Formats The markup in a typical XML document describes the document s structure but it should not describe the document s layout It says how the document is organized but not how it looks Although XML documents are plain text and someone could read them in native form it is much more commonly an XML document is ren dered into some other format before being presented to a human audience One of the key ideas of markup languages in general and XML in particular is that the input format need not be the same as the output format The input markup language is designed for the convenience of the writer The output language is 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 50 designed for the convenience of the reader Of course this requires a means of transforming the input format into the output format Most XML documents undergo some kind of transformation before being presented to the reader The transformation may be to a different XML vocabulary like XHTML or XSL FO or it may be to a non X
99. s support XML a Date 2002 12 09 Person PK Feature Information and layout Shape B Support for structures and formats Weak Target application Browsing Database Id zw value gt Recommended for documentation No Yes NEREABE Ma 2 2 FrameMaker rine FrameMaker Version 7 can generate XML if special XML Tools are available lt no value gt Use FM 1 if you work with XML documents availability in September 2004 A A Paragraph Update tje current FM7 0 Version to p578 for correct XML generation Older versions caused errors in cre elements NewPage Update Steps Paragraph 4 Free update can be done via www adobe de supportdownloads main html 2 Update first to FrameMaker 7 0p576 3 Update to FrameMaker 7 0p578 7 3 w A E Paragraph 3 Gor 22 100 2 Ze Doc writers guide 100261 1ZIsi2 NewPage Figure 3 2 FrameMaker in structured mode 3 2 2 Use of FrameMaker s XML export The possibility to export XML from a FrameMaker document is currently used to apply certain automated steps onto a document These automation would be too difficult to be applied on FM documents directly with the help of a scripting language or through the FrameMaker API Therefore the documents are exported as XML and afterwards a few XSLTs are used to perform tasks like e generating so called special chapters which include the content of a normal chap ter in
100. ss of values in an instance e Data type declaration for elements and attributes The listing below points out the differences between XML Schema and Document Type Definition It shows the Schema for the same example that has been used in section 2 1 At first glance it can be seen that the definition is far more complex than the one used in a DTD For a complete explanation of each of these tags please refer to 6 lt xml version 1 0 gt lt xs schema xmlns xs http www w3 org 2001 XMLSchema gt lt xs element name Book gt lt xs complexType gt lt xs sequence gt lt xs element name Title minOccurs 1 maxOccurs 1 gt lt xs element name Author minOccurs 1 maxOccurs unbounded gt lt xs element name PublishingDate minOccurs 1 type xs date gt lt xs element name Chapter gt lt xs complexType gt lt xs sequence gt lt xs element name ChapterTitle minOccurs 1 maxOccurs 1 gt lt xs element name Paragraph minOccurs 1 maxOccurs unbounded gt lt xs complexType gt lt xs simpleContent gt lt xs extension base xs string gt lt xs attribute ref ID type xs ID gt lt xs extension gt lt xs simpleContent gt 2 2 STRUCTURE OF XML DOCUMENTS 10 lt xs complexType gt lt xs element gt lt xs sequence gt lt xs attribute ref ID type xs ID gt lt xs complexType gt lt xs element
101. t The nesting of elements in a DTD can be constrained by adding special char acters to the elements name To indicate how many of that elements are expected at that position the following syntax is used means zero or one means zero or more means one or more If none of these characters is added the element is required exactly once The simplest content specification is one that says an element may only contain parsed character data but may not contain any child elements of any type In this case the content specification consists of the keyword PCDATA inside parentheses With the ATTLIST keyword one or more attributes can be defined for an ele ment In this case only the IDs for Chapter and Paragraph were defined and set as REQUIRED so they cannot be omitted 2 2 2 XML Schema The World Wide Web Consortium W3C began work on XML Schema 6 in 1998 and the first version became official in May 2001 The intent was to create a schema language that is more expressive than DTDs supports namespaces and unlike DTDs uses XML syntax 7 Schema provides the following features in addition to the advantages already men tioned above at section 2 2 1 they are e Simple and complex data types e Type derivation and inheritance 2 2 STRUCTURE OF XML DOCUMENTS 9 e Element occurrence constraints e Namespace aware element and attribute declaration e Control over the uniquene
102. t lt p gt In 1950 lt p gt Figure 4 8 Workflow to convert XML to HTML 4 3 2 Windows Help file HTML Help is the help format introduced by Microsoft with Windows 98 With this format help files are built from HTML text The most important disadvan tages of HTML Help are that it requires Microsoft Internet Explorer 4 or later plus the HTML Help ActiveX library On Windows 95 or NT4 using HTML Help is not recommended These operating systems do not support HTML Help out of the box and Windows 95 machines are probably too slow to work with HTML Help comfortably But HTML Help is also the help system used by Microsoft s NET framework 27 4 3 TRANSFORMATION TO DIFFERENT OUTPUT FORMATS 53 One reason to use HTML Help is that some customers will expect to receive doc umentation in help file format of Windows especially when developing software for Windows platforms However it would also be possible to document any hard ware related information e g chip specifications with these help files HTML Help is not a plain HTML format instead it is Windows Compiled HTML Help CHM format Therefore you need a special program to turn you HTML pages into chm files this is the HTML Help Compiler HHC that comes with Microsoft HTML Help 1 4 SDK Figure 4 9 shows the workflow to turn XML data to CHM format XML 4 markup text data markup text data proprietary binary data F
103. t or occasionally other items such as an image or ahorizontal rule There are two kinds of boxes that are created by particular elements in the formatting objects document e Block areas e Inline areas For the most part the rendering engine decides exactly where to place the boxes and how big to make them based on their contents However properties for these boxes that adjust both their relative and absolute position spacing and size on a page can be specified Most of the time the individual boxes don t overlap But they can be forced to do so by setting the properties absolute position left top right and top on the boxes Considered by itself each box has a content area in which its content generally text but possibly an image or a rule is placed This content area is surrounded by a padding area of blank space An optional border can surround the padding The size of the area is the combined size of the border padding and content The box may also have a margin that adds blank space outside the box s area as shown in figure 2 3 Text here inside content padding border margin Figure 2 3 Parts of an XSL FO area The elements in the XSL FO document do not map in a one to one fashion to the boxes on the page Instead the XSL FO document contains a slightly more abstract representa tion of the document The formatting software uses the XSL FO elements to decide which 2 5 ASP NET AND
104. technical doc umentation The first problem is a common one that FrameMaker shares with Word or Excel and that is the file format that is used to store the data in FrameMaker uses a proprietary file format that even differs from FM version to version and there are certain incompatibilities known among FrameMaker version 5 and 6 to 7 However the greatest disadvantage of such an proprietary format is that it cannot or can only hardly be processed by any other software But the need to extract certain data out of an technical document exists and should not be underestimated That is one reason why open formats like XML are gaining more and more importance in the area of Technical Communication The whole process of technical documentation is described in figure 3 1 which is not 3 2 THE CURRENT PROCESS IN TECHNICAL DOCUMENTATION 27 very detailed but should give a good overview The area labeled A shows the creation and modification process and B describes the publication process A Product Information y Creation and modification of documents ty Framemaker documents Local or shared drives Y Manual conversion FM to PDF Y Marketing Department Y Customer Figure 3 1 Internal documentation process To give a short overview what document types are treated here I want to give a short list of types that a
105. tion switching voltage stabilisation signal modulation and many other functions It acts as a variable valve which based on its input current BJT or input voltage 79 FET allows a precise amount of current to flow through it from the circuit s voltage supply lt paragraph gt lt paragraph gt In essence it has three terminals lt crossRef Idref CEGHDIBB type FigureTitle gt A current or voltage applied through across two terminals controls a larger current through the other terminal and the common terminal In analog circuits transistors are used in amplifiers Analog circuits include audio amplifiers stabilised power supplies and radio frequency amplifiers In digital circuits transistors function essentially as electrical switches Digital circuits include logic gates RAM random access memory and microprocessors lt paragraph gt lt paragraph gt Transistor was also the common name in the sixties for a transistor radio a portable radio that used transistors rather than vacuum tubes as its active electronic components lt figure gt lt image file http localhost showcase db IT 20BT content transistor images trans jpg height 100pt width 216pt position below sideways 0 impang 0 000 nsoffset 0 000in gt lt figtitle id CEGHDIBB gt Transistors tape measure marked in centimeters lt figtitle gt lt
106. to elements and so forth This grammar is spe cific enough to allow the development of XML parsers that can read any XML document Documents that satisfy this grammar are said to be well formed Doc uments that are not well formed are not allowed Similar to a C program that contains syntax errors XML processors will reject documents that contain well formedness errors 4 The markup permitted in an XML document can also be restricted with the use of a so called schema which allows not only to check for well formedness but also if a document is valid against that schema This issue will be covered in detail in section 2 2 2 1 XML 5 To get a first impression of what a XML document could look like a simple example is listed below These few lines loosely describe the structure of a book Nonetheless this is a well formed document and XML parsers can read and under stand it In addition this sample document will also be the basis for all examples that will be treated throughout the next sections lt xml version 1 0 gt lt Book gt lt Title gt 16 Bit CMOS Microcontroller lt Title gt lt Author gt Johann Beispiel lt Author gt lt PublishingDate gt 2002 05 20 lt PublishingDate gt lt Chapter ID c100 gt lt ChapterTitle gt Introduction lt ChapterTitle gt lt Paragraph ID p100 gt The 16 Bit CMOS Microcontroller is lt Paragraph gt lt Chapter gt lt Book gt Co
107. ts Chapter and section numbering is done by counting the specific elements Additionally internal links are included to allow the user to jump to each part of the book directly from the table of contents The destination of each link is specified by the unique ID each chapter or section carries lt l PERHERE TOC PEPPER EEE EEE EEE EEE gt lt fo page sequence master reference A4 gt lt fo flow flow nam xsl region body gt lt xsl for each select book part gt lt Do the Chapter numbering gt lt xsl variable name chapternumber gt lt xsl number count part format 1 gt lt xsl variable gt lt xsl for each select document link chapter gt lt fo block text align right gt lt fo inline keep with next within line always gt lt xsl value of select Schapternumber gt amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 amp x00a0 8 amp x00a0 amp x00a0 lt fo basic link internal destination id color blue gt lt xsl value of select title gt lt fo basic link gt lt foriniline gt lt fo inline keep together within line always gt lt fo leader leader pattern dots leader pattern width 4pt leader alignment reference area keep with next within line always gt lt fo page number citation ref id id gt lt fo inline gt Stor bleck gt
108. voltage is made more positive the source drain current will increase GI For P channel devices the polarities are reversed Most IGFETs are enhancement mode types and nearly all JFETS are depletion mode types lt paragraph gt lt chapter gt Appendix B XSL Transfomation With this stylesheet transformation it is possible to combine XML modules to a single file when they are referenced as it is stated above in the book xml Furthermore this stylesheet generates a table of contents and dissolves cross ref erences of the input XML files The result is a nicely formatted XSL FO based book book2fo xsl lt xml version 1 0 encoding ISO 8859 15 gt lt xsl stylesheet version 1 0 xmins xsl http www w3 org 1999 XSL Transform xmlns fo http www w3 org 1999 XSL Format gt lt xsl output omit xml declaration no method xml encoding UTF 8 indent yes gt Here the stylesheet parameter that is used for the editable PDF functionality is initialised The testing wether it should be enabled or not is done below lt Stylesheet Parameters FFEETETEE EEE Eh gt lt xsl param name editsource gt lt gt lt Includes FHFEFEEFEEEEEEEEEEEEEE gt lt xsl include href wg page header footer xsl gt lt gt 82 83 The serverPath variable is used to find the source document on the server if the editable PDF functional
109. w name xsl region after gt lt fo block font family Helvetica font size 10pt gt lt fo table table layout fixed width 100 border top width 0 5pt border top style solid border top color black gt lt fo table column column number 1 column width proportional column width 1 gt lt f O column wid lt to column wid lt EoE Lo lt Eo EO Eog lt fo lt fo lt fo lt rfo table body gt table column co Lumn number 2 th proportional co umn width table column column number th proportional col zn umn width table row height 12pt gt 95 Ly ee HORE table cell text align left display align after gt block gt block gt block gt table cell gt table cell text align center display align after gt block gt lt fo block gt lt fo page number gt lt fo block gt lt fo lt fo lt Eor EG LEOS af EO lt fo lt fEO lt fo lt p EO ae pine ESS lt xs lt xsl stylesheet gt sblock gt table cell gt table cell text align right display align after gt block gt block gt block gt table cell gt table row gt table body gt table gt iblock l template gt static content gt List of Figures 24 2 2 2 3 gt 3 2 33 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 4 10
110. will run on a partic ular operating system Readers familiar with Java will no doubt recognize the resemblance to Java byte code and the Java Virtual Machine In addition to this degree of platform and operating system independence the CLR pro vides another significant benefit Programs running within the CLR are contained They do not directly inter face to the operating system and are limited to the address space provided by the CLR This prevents the accidental and sometimes deliberate invasion of the address space used by the operating system or by other programs In addition to increasing program and operating system stability this also in creases security It s harder for malicious code to reach places to damage The CLR also provides for garbage collection automatic freeing of memory after object use and support for metadata used to describe and control class use The NET framework class library provides a set of classes that provide essential functionality for applications built within the NET environment Web functionality XML support database support threading and distrib uted computing support is provided by the NET framework class library Another great advantage is the separation of semantics and syntax for an entire family of programming languages The semantics of a programming language are its underlying sense its meaning This includes the data types it allows its rules for type inheritance and the types of const
111. with which XML schema to use what secu rity to put in place how to chain electronic messages e g does Coyote invoice ACME for every order or does it issue a monthly invoice what communication protocols to adopt There are also many parameters to get right the address of the server time outs and more Currently setting up an XML connector is a lengthy and costly business It requires many back and forth meetings phone calls between trained professionals and generally speak ing it is not very efficient Figure 4 2 is the ebXML equivalent of figure 4 1 The only difference but a significant one is that the slow and costly process of setting up the connector has been automated Coyote Industries Figure 4 2 An Electronic Business Scenario with ebXML according to 22 It starts step 1 with ACME looking up Coyote information in a registry A registry is an open directory where companies list a very detailed description of their electronic capa 4 1 XML BASED TECHNICAL DOCUMENTATION 38 bilities In ebXML lingo the description is known as a Collaboration Protocol Profile CPP The CPP contains the answer to the questions discussed in the previous section which XML schemas Coyote recognizes the security mechanisms it has put in place the address of its server and much more In a second step ACME matches Coyote description with its own to find commonali ties In the process it creates a Collaborative Partner Agreeme

XML-centered Information Handling in Technical

Contents

Download Pdf Manuals

Related Search

Related Contents