xprocdoc.xprocdoc.xpl Maven / Gradle / Ivy

Go to download


  
    A simple Javadoc-style XProc API documentation generator written in XProc and XSLT 2.0.

    The documentation for the XProc pipelines is specified inline, in the actual source files, similar to Javadoc comments in Java source files. The documentation takes the form of XHTML fragments wrapped in the standard XProc p:documentation element, and can be provided for the following XProc elements:

    
      p:library - A library containing zero or more XProc steps:
      
  
    Library for simple DITA processing.
  

  
    ...
  
  ...
]]>

      p:declare-step and p:pipeline - An XProc step:
      
  
    This pipeline transforms a DITA topic to XHTML.
  
  ...
]]>

      p:input - An input port of a step:
      
  
    
      The DITA topic to transform.
    
  
  ...
]]>

      p:output - An output port of a step:
      
  ...
  
    
      The generated XHTML document.
    
  
  ...
]]>

      p:option - An option of a step:
      
  ...
  
    
      This option indicates whether to validate the
         topic before it is processed. The value of the
         option must be a boolean.
    
  
  ...
]]>
    

    To generate the XHTML documentation for a set of XProc files, simply pass the files to the source input port of the xd:xprocdoc step. The step will process the XProc sources and will generate a set of XHTML files in the current working directory (or in a location specified using the output-base-uri option). The file index.html can be used to access the documentation overview page.

    The xd:xprocdoc step generates documentation for all XProc steps that are:
    

      direct children of p:library and specify the type attribute; or
      top-level steps (i.e. not contained in p:library) with or without the type attribute.
    

    (In other words, documentation will be generated only for those steps that can be used by developers, either directly or by importing an XProc library.)

    Steps can also be explicitly excluded from the generated documentation by setting the exclude attribute (in the http://github.com/vojtechtoman/xprocdoc namespace) to true on the step's p:declare-step or p:pipeline element:

    
  ...
]]>

    The documentation generation pipeline also follows p:import statements in XProc libraries. That way, the documentation can be generated for the complete dependency set. (The pipeline supports re-entrant and circular imports.)
  

  
    
      The pipelines or pipeline libraries to process.
    
  

  
    
      A sequence of c:result documents pointing to the generated documentation files.
    
  

  
    
      The name of the product that will appear on the generated overview XHTML page.
    
  

  
    
      The base URI of the source XProc pipelines. This parameter can be used to customize the way the source URIs are presented in the generated XHTML. For example, if the source pipelines src1.xpl and src2.xpl are stored in the directory with the base URI file:/home/fred/pipelines/, setting the input-base-uri option to file:/home/fred/ will cause the pipelines to appear as pipelines/src1.xpl and pipelines/src2.xpl. If the input-base-uri option is left unspecified, the pipelines will appear as file:/home/fred/pipelines/src1.xpl and file:/home/fred/pipelines/src2.xpl
    
  

  
    
      The base URI of the directory where the generated XHTML output is stored. If not specified, the current working directory will be used.
    
  

  
    
      The URI of a file with an XHTML boilerplate text that will be inserted in the generated overview page. If not specified, no boilerplate text will be inserted.
    
  


  

  
    
    
      
        
      
    
    

    
    
    
      
        
        
          
            
          
        
      
      
        
          
            
          
        

        
        
          
            
          
          
            
          
        

        
        
          
            
          
          
            
          
        
      
    
  

  

  
    
    
    
    
    
    
      
        
          
            
          
        
      
      
        
          
            
          
          
        
      
      
        
          
            
              Unsupported document element. One of p:library, p:declare-step, or p:pipeline expected
            
            
          
        
        
          
            
          
        
      
    
  

  

  
    
    
    

    

    
      
        
          
        
        
        
          
        
        
      

      
        
        
          
          
            
              
                
              
            
            
              
            
          
          
            
              
            
            
              
                
                  
                
              
            
            
              
            
          
        
        
        
          
          
            
              
            
            
              
            
          
        
        
        
          
            
          
          
            
          
        
        
        
          
            
          
          
            
          
        
        
        
          
            
            
          
        
        
        
          
            
          
          
            
          
        

        
          
            
          
          
            
          
          
        
      
    
  

  

  
    
    
    
      
    
    
      
    

    

    
      
        
        
          
        
        
          
        
        
      
      
        
          
          
        
        
          
        

        
          
            
          
        

        
        
          
            
          
          
            
          
        

        
        
          
            
          
          
            
          
        
      
    

  

  

  
    
    
    
    
      
    

    

    
      
        
          
        
        
        
          
        
        
      

      
        
          
        
        
          
        
        
          
            
          
        
      
    

    
    
      
        
          
        
      
      
    
  

  

  
    
    
    
    

    

    
      
        
          
        
        
        
          
        
        
      

      
        

        
          
          
            
              
                
              
            
            
              
            
          
          
            
              
            
            
              
                
                  
                
              
            
            
              
            
          
        

        
          
          
            
              
            
            
              
            
          
        

        
        
          
            
          
          
            
          
          
        

        
          
            
          
          
            
          
          
        
      
    
  

  

  
    
    
    

    

    
      
        
        
          
            
          
        
      
      
        
          
            
          
        

        
        
          
            
          
          
            
          
        

        
        
          
            
          
          
            
          
        

        
          
            
            
          
        
      
    
  

  

  
    
    
     
    
    

    
      
        
        
        
        
        
          
        

        
          
        

        
          
        

        
          
        

        
          
            
            
            
              
                
                  
                
                
                  
                
                
                  
                
              
            
          
          
            
            
          
        

        
        
        
          
          
            
              
            
            
            
              
            
          
        
        
        
          
          
            
              
            
            
            
              
            
          
        
        
        
          
          
            
              
            
            
            
              
            
          
        
        
        
          
          
            
              
            
            
            
              
                
              
              
              
            
          
        
        
        
          
          
            
              
              
              
              
            
          
          
          
            
          
          
            
          
          
            
          
          
            
          
          
            
          
          
            
          
        

        
          
            
          
          
            
          
        
      

      
        
        
          
            
          
        
      
    
  
      
  

  
    
    

     
     

    
      
      
        
          
            
              
                
              
            
          
        
        
          
            
              
                
              
            
          
        
        
          
            
              
                
              
            
          
        
        
          
            
              
                Unsupported port type. One of 'input', 'parameterinput', or 'output' expected.