1. Embedded XML Documentation for Fortran 90 and C/C++ Brett N. DiFrischia RS Information Systems NOAA | GFDL

2. Documentation Foundation of successful software projects Eases development and implementation An absolute necessity for large applications and libraries Often the least maintained portion of any software development effort

3. Example

4. Embedded Documentation Benefits Comments next to definition One file to maintain Drawbacks Not easy to navigate Documentation may not be near source counterpart Documentation may not be there at all

5. HTML Documentation Benefits More navigation options Easier to read Can be more organized Drawbacks More files to maintain May need to know HTML to do so Difficult to follow a standard interface Change in format requires change in all HTML files

6. How Can XML Help? Structured data User defined elements Optional validation Many parsers available Standards for transformation –XSLT –XSL:FO

7. Example

8. Embedding XML in Source Identify information to be included Must be in comments Easy to extract –Assuming there is a way to separate source from comments Perform minimal automated enhancements –Identify external dependencies

9. Example

10. Example (cont.)

11. Extracting XML Must be able to separate comments Replace <‘s and &’s with < and &, respectively –Regular expressions can handle this Parse XML –Typically requires native library Remove private text

12. Transform Web pages –Directly translate, via parser –Translate using XSLT Transform to different format (XML, HTML, etc.) Printed page –XSL-FO Transform to printable format (typically PDF) Interactive –E.g.. AxKit

14. Software Primarily Perl programs –Modules are either included with the package or downloadable from CPAN External C libraries –Expat –LibXML2 (in the near future) Java program –Xalan

15. Future Versions More flexible handling of DTDs –Determine element lists using DTDs (internal) W3C XML Schema dependencies –Specific type enforcement Optional validation of XML –Simple enforcement of documentation standard

16. Highlights Single file to maintain Tags are easy to remember Standardizes appearance Eases transition between document formats Supports adherence to documentation standards Simplifies documentation creation

17. For More Information Web pages –http://www.gfdl.noaa.gov/~bnd/fms/xml_doc.htmlhttp://www.gfdl.noaa.gov/~bnd/fms/xml_doc.html –http://www.gfdl.noaa.gov/~bnd/fms/gen_html.htmlhttp://www.gfdl.noaa.gov/~bnd/fms/gen_html.html Books –Inside XML Steven Holzner, New Riders Pub., 2000 –Inside XSLT Steven Holzner, New Riders Pub., 2002 –XML in a Nutshell, 2 nd Edition Elliotte Rusty Harold, W. Scott Means, O’Reilly & Associates, 2002