From 3aadf08ddb860b62c1b2007137ec874aa8d49ccc Mon Sep 17 00:00:00 2001 From: "rginda%netscape.com" Date: Fri, 3 Mar 2000 19:59:54 +0000 Subject: [PATCH] updated readme, add comments to parse_apidoc.pl, make parse_devedge_doc.pl exit on startup, remove zpidoc.xml (it's in mozilla.org/projects/apidoc) --- webtools/apidoc/README | 37 +- webtools/apidoc/docs/apidoc.xml | 530 --------------------------- webtools/apidoc/parse_apidoc.pl | 37 +- webtools/apidoc/parse_devedge_doc.pl | 10 + 4 files changed, 69 insertions(+), 545 deletions(-) delete mode 100644 webtools/apidoc/docs/apidoc.xml diff --git a/webtools/apidoc/README b/webtools/apidoc/README index 0f2dc5e539f3..38c1d1523f5c 100644 --- a/webtools/apidoc/README +++ b/webtools/apidoc/README @@ -1,17 +1,17 @@ +DESCRIPTION: +APIDOC tool source. +Generates HTML API documentation from an xml source. + +-- FILES: -===* parse_devedge_doc.pl -Requires: - nothing. - -Description: - Parses the nasty devedge document (jsref.htm) into somewhat nicer xml. - -Syntax: - perl parse_devedge_doc.pl < jsref.htm > jsref.xml ===* parse_apidoc.pl + +Syntax: + perl parse_apidoc.pl jsref.xml [] + Requires: XML::Parser (http://search.cpan.org/search?dist=XML-Parser) @@ -21,7 +21,24 @@ Description: specified. Output pages with content will refer to api-content.css, table of content pages will refer to api-toc.css. +See Also: + http://www.mozilla.org/projects/apidoc + +===* parse_devedge_doc.pl + Syntax: - perl parse_apidoc.pl jsref.xml [] + perl parse_devedge_doc.pl < jsref.htm > jsref.xml + +Requires: + nothing. + +Description: + Parses the nasty devedge document (jsref.htm) into somewhat nicer xml. + The XML source, jsref.xml, located at + http://www.mozilla.org/js/apidoc/jsapi.xml is now the authoritative place to + make changes. + This file should be considered dead. Do not use it. It is here for emergency + use only. + REPEAT: DO NOT USE THIS SCRIPT! diff --git a/webtools/apidoc/docs/apidoc.xml b/webtools/apidoc/docs/apidoc.xml deleted file mode 100644 index 9771565d94cc..000000000000 --- a/webtools/apidoc/docs/apidoc.xml +++ /dev/null @@ -1,530 +0,0 @@ - - - - - - - - - - The APIDOC namespace provides a way of describing an API - in XML. - - - APIDOC is an XML based API documentation system which allows the - document writer to create document content using a set - of logical tags in an XML file. A perl script, parse_apidoc.pl, - processes the source XML, and generates a collection of HTML files - suitable for web publishing. -

- The set of tags available in APIDOC is very small compared to HTML, - and can be broken down into three groups. These are Organizational, - Formatting, and Other. Organizational tags are - logical sections of an API document, such as an ENTRY, a - DESCRIPTION or an EXAMPLE. Formatting tags provide - a set of basic format control tags, such as B and - I, as well as intelligent tags like C and - S which automatically create links to other ENTRYs or - external documents. The group of tags classified as Other don't - fit into either of the other two categories, but don't warrent a group - of their own. -

- See the README for instructions on how to run APIDOC. - - - Tags and attributes are case sensitive. In APIDOC, all - tag names are in UPPERCASE, and all attribute names are - lowercase. -

- The document you are reading was created with APIDOC, see - http://www.mozilla.org/projects/apidoc/apidoc.xml for the - source. -

- APIDOC was originally written to allow engineers in the JavaScript - group at Netscape to maintain their own documentation on the JavaScript - Embedding API. That document is available from the - JavaScript Page on - mozilla.org - - - - -

- Container for all other tags. - - - - . . . - - - Identifier for the API. - - - The APIDOC version expected by the contained tags. Currently - this attribute is ignored. - - - - The API tag is the top level container for all other tags. It is - analogous to the HTML tag in used in HTML documents. Unlike in HTML, - if tags appear outside of the API tag, the file will fail to - parse. - - - - - - - An entrypoint in the API. - - - - . . . - - - Identifier for the entrypoint. - - - - The ENTRY tag declares an API entrypoint you wish to document. - It serves as the container for most other Organizational tags. - - Entries can be referenced in SEEALSO tags. If text appearing - in a C tag, is also an ENTRY, a link will be created. - - - - - - - Indicates the type of an ENTRY. - - - - - Type of the entry. - - - - The value attribute should be used to describe the ENTRYs - type. For example, documentation on a C based API may use 'Macro', - 'Data Structure' and 'Function' as types, while this document - uses 'Organizational', 'Formatting', and 'Other' - as type names. -

- When a TYPE tag is encountered, a new GROUP - is created (if it doesn't already exist), and the ENTRY which - contains the TYPE tag is added to that group. In addition, - the new GROUP is automatically added to the 'Groups' portion of - 'See Also' for that ENTRY. - - - - - -

- A brief summary for the ENTRY. - - - - . . . - - - - Gives the user a brief overview of the ENTRY's purpose. See the - 'Sumamry' of this entry for an example. - - - - - - - Syntax for using the ENTRY. - - - - . . . - - - - Shows the user an abstract use of the ENTRY. PARAM - tags can be contained by the SYNTAX tag to further illustrate - parameters. Text inside SYNTAX tags will be rendered in a - monospace font using the PRE HTML tag. Leading spaces in the text - contained in a SYNTAX tag are converted to - entities. Use the EXAMPLE tag for concrete examples. - - - - - - - Description for a paramater used by the ENTRY - - - - . . . - - - The name of the parameter. - - - The data type of the parameter. - - - - Used to describe a parameter used by the ENTRY. PARAM - tags can only be contained inside SYNTAX tags. Multiple - PARAM tags can appear in a SYNTAX tag (typically one - for each parameter). PARAM tags will be displayed in the - order they appear. - - - - - - - - - - Description for the return value of the ENTRY - - - - . . . - - - Optional. The name of the return value. - - - The data type of the return value. - - - - RETVAL works exactly like the PARAM tag, with the - exception that the name attribute is optional. If - name is omitted, it defaults to the string "Return Value". - - - - - - - Long description for the ENTRY - - - - . . . - - - - Contains a long description of the ENTRY. Literal HTML can - be included using a - ![CDATA[ . . . ]] tag. The CDATA - 'trick' can actually be used inside any APIDOC tag, but is most - useful for DESCRIPTIONs. - - - - - - - An example usage the ENTRY. - - - - . . . - - - Short description of what the example shows. - - - - Contains a "real world" example of the ENTRY being used. - As with the SYNTAX tag text inside EXAMPLE tags will - be rendered in a monospace font, and leading spaces are significant. - The desc attribute can be used to provide a short caption for the - example. - - - - - - - Important notes about the ENTRY. - - - - . . . - - - - Contains notes about the entry that should stand out from the - description for one reason or another. If an entry is deprecated, - the NOTES section would be a good place to explain why. - - - - - - - Associate one ENTRY with another. - - - - - The id of a related ENTRY. - - - - Associates one entry with another. Multiple SEEALSO tags - can appear in an ENTRY. Using an entry in a C tag - creates a SEEALSO tag for it automatically. The - EXTERNALREF tag can be used to attach references to external - documents to entries. - - - - - - - Marks an ENTRY as deprecated. - - - - - - Marking an entry as DEPRECATED tells would-be users that - the use of that ENTRY is not advised. Further information - can be placed in the DESCRIPTION or NOTE tag. Marking - an entry as DEPRECATED automaticall makes it a member of the - 'Deprecated' GROUP. - - - - - - - An external source with more information about the API. - - - - - A text description of the reference. - - - The URL for the reference. - - - - EXTERNALREFs will be added to the 'See Also' portion of - an ENTRY. If an EXTERNALREF appears as a child of the - API tag, and the value of the URL contains the characters - '{e}', the reference will be attached to every entry, and the - ENTRYs id will be substitued in for '{e}'. If '{e}' does - not appear in the value attribute, APIDOC assumes that this - EXTERNALREF applies to the API as a whole, and only lists it in - the table of contents. -

- If an EXTERNALREF appears as a child - of an ENTRY tag, it will only appear in that ENTRYs - 'See Also' section. -

- Multiple EXTERNALREF tags can appear as children of both - API and ENTRY tags. - - - - - -

- Includes an ENTRY in a group. - - - - - The name of the group. - - - The id of the ENTRY to add to the group. Optional - (and ignored) if the GROUP tag appears as a child of - an ENTRY tag, in which case the id of the containing - ENTRY is used. - - - - For each unique GROUP name appearing in the API, a subheading - will appear in the Table of Contents, listing each member of the - GROUP. Multiple GROUP tags can appear as children of - the API tag. The GROUP tag can appear as a child of - either the API tag, or an ENTRY tag. When a GROUP - is parented directly by the API tag, both name and - value attributes must be specified. When a GROUP tag - is parented by an ENTRY tag, the id of the containing - ENTRY is used in place of the value attribute. -

- Marking an item as DEPRECATED automatically makes it a member - of the group named 'Deprecated'. Using the TYPE tag - in a n ENTRY automatically makes the ENTRY a member of - a group of the same name as given in the value attribute of - the TYPE - - - - - -

- Marks text as code. - - - - - - Any text contained in a C tag will appear in a monospace - font, rendered using the CODE HTML tag. In addition, if the text is a - ENTRY id (but not the current ENTRY), a link will - be created to the ENTRY in the text, and a SEEALSO tag - will be generated. -

- For example, all of the links in this body of text - were generated by wrapping the plain text in a C - tag. APIDOC - checks to see of the contained text is a valid ENTRY, and if so, - assumes that's what you were talking about. If the contained text is - not a valid ENTRY, or it is the current entry, the text - is rendered in a HTML CODE container, and no links are generated. - - - - - -

- Marks the beginning of a new paragraph. - - -. . . - - - Marks the start of a new paragraph. Unlike in HTML, P tags - are not containers. That is, the only valid P tag is the one - shown here. - - - - - - - Marks text as bold. - - - - - - Any text contained in a B tag will appear bold. This tag - functions exactly like the B tag in HTML. - - - - - - - Marks text as italic. - - - - - - Any text contained in a I tag will appear in italics. This tag - functions exactly like the I tag in HTML. - - - - - - - Creates an inline link to an EXTERNALREF or GROUP. - - - - - - If the text wrapped in an S tag is a valid GROUP - (including a GROUP implied by a TYPE or DEPRECATED - tag) a link to the referenced group will be created in addition to the - text. If instead, the text matches a valid EXTERNALREF tag, a - link to the external reference will be created. -

- In both cases, an appropriate entry is added to the ENTRYs 'See - Also' section. - - - If the text contained by an S tag does not match any GROUP - or EXTERNALREF, the parse will fail. - - - - - - - - - - - - - diff --git a/webtools/apidoc/parse_apidoc.pl b/webtools/apidoc/parse_apidoc.pl index b321f86c4684..5f1b59791f4a 100644 --- a/webtools/apidoc/parse_apidoc.pl +++ b/webtools/apidoc/parse_apidoc.pl @@ -93,9 +93,17 @@ my @CODE_TAGS = ($TAGS[$SYNTAX], $TAGS[$EXAMPLE]); my $URLVAR_ENTRY = "{e}"; my $footstr = "

This page was generated by " . - "APIDOC" . + "" . + "APIDOC" . "
\n"; +my $WARNING = "\n"; + my $JS_COMPLETE = ("\n