From 181e8d7dd70a912c7f00b9699b9f5054662e962f Mon Sep 17 00:00:00 2001 From: richard Date: Wed, 21 Jun 2000 17:28:00 +0000 Subject: [PATCH] Tidy documentation git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@6762 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 3 +- Tools/Makefile.postamble | 2 +- Tools/gsdoc-0_6_6.dtd | 4 +- Tools/gsdoc.gsdoc | 259 ++++++++++++++++++++++++++++++++++++++- 4 files changed, 260 insertions(+), 8 deletions(-) diff --git a/ChangeLog b/ChangeLog index a02c11f4a..474d0addf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -10,7 +10,8 @@ * Documentation/gsdoc/NSScanner.gsdoc: fleshed out * Tools/Makefile.postamble: Added documentation target - build before install - * Tools/gsdoc-0_6_6.dtd: New dtd under development - add java support + * Tools/gsdoc-0_6_6.dtd: New dtd under development - add java support, + permit multiple indices at end of document, permit
element. * Tools/gsdoc.m: Update to work with current dtd * Tools/gsdoc.gsdoc: Add a little more text on document body structure. diff --git a/Tools/Makefile.postamble b/Tools/Makefile.postamble index 92a042ba8..733f154fe 100644 --- a/Tools/Makefile.postamble +++ b/Tools/Makefile.postamble @@ -78,6 +78,6 @@ copy-dist: $(DIST_FILES) cp $$f ../snap/Tools ; \ done -documentation: $(GNUSTEP_OBJ_DIR)/gsdoc +documentation: gsdoc $(GNUSTEP_OBJ_DIR)/gsdoc gsdoc diff --git a/Tools/gsdoc-0_6_6.dtd b/Tools/gsdoc-0_6_6.dtd index 08657dffc..3c68ead65 100644 --- a/Tools/gsdoc-0_6_6.dtd +++ b/Tools/gsdoc-0_6_6.dtd @@ -419,10 +419,10 @@ - - + diff --git a/Tools/gsdoc.gsdoc b/Tools/gsdoc.gsdoc index bc471d127..478365550 100644 --- a/Tools/gsdoc.gsdoc +++ b/Tools/gsdoc.gsdoc @@ -271,7 +271,7 @@ <chapter> <heading>Afterword</heading> <p> - Adn after the main part of the doucment we can have some other stuff. + And after the main part of the doucment we can have some other stuff. </p> </chapter> <index type="class"/> @@ -282,7 +282,7 @@ The above example shows all the elements possible in a document body -

- + front This is an optional part of the document that can come before the main text. Typically, this could be used to contain an automatically @@ -290,26 +290,277 @@ When output is generated in book form, this part of the document would probably have a different page numbering scheme from the main part. +

+ The contents element is used as a marker to specify + that an automatically generated contents page (listing the + chapters in the document) is to be inserted. +

- +

After the front part of the document body comes a mandatory sequence of one or more chapters. This is where the main part of the document resides. + Each chapter consists of a + heading, any number + of blocks of information, and any number of sections.

- + back After the chapters making up the main part of the body of the document is an optional back part which may contain chapters (such as appendices) possibly followed by an automatically generated index. +

+ The index element is used as a marker to specify + that an automatically generated index is to be inserted. + The type attribute of the index specifies what sort + of item is to be in the index - the default type of label + causes an index of all label and entry + elements to be generated. +

+ + Element reference +
+ block +

+ Actually, there is no such thing as a block element, this + is just shorthand for refering to a group of elements that can be + used in similar ways. The block elements are - +

+ + embed + embeded information from elsewhere + example + the example + p + the paragraph + + + A variety of lists. + + list + a simple list of items + enum + an enumerated list + deflist + a list of terms and their definitions + qalist + a list of questions and answers + + + def + + A variety of specialised elements for software documentation. + + class + An Objective-C class definition + jclass + A Java class definition + category + An Objective-C category definition + protocol + An Objective-C protocol or Java interface definition + function + A function definition + macro + A macro definition + type + A type definition + variable + A variable definition + + + +
+ +
+ br +

+ The br element is an empty element that always appears + as <br/> in the document. This element simply specifies + that a line-break should appear in the output text at this point. +

+
+ +
+ chapter +

+ This is the basic unit of the document - the main part of + a document body will contain at least + one chapter. + Each chapter consists of a heading, + zero or more blocks, + and zero or more sections. +

+

+ Each chapter in the document is automatically listed in the + documents contents page (if it has one). +

+
+ +
+ class +

+ This is the main element for Objective-C code documentation. + The name attribute is required for this element - it is + the name of the class. The super attribute is normally + necessary to provide the name of the superclass. +

+

+ The elements in a class are - an optional + declared element, + zero or more conform element, + an optional description, + zero or more method elements, + and an optional standards element. +

+
+ +
+ conform +

+ This element contains simple text giving the name of a protocol + or interface to which a class conforms. +

+
+ +
+ declared +

+ This element contains simple text giving the name of the header + file in which something is declared. +

+
+ +
+ desc +

+ This element is used to contain descriptions of how software + functions. It may contain text, but may + also contain lists, + paragraphs, + examples and + embedded data. +

+
+ +
+ heading +

+ Each chapter, + section + sub-section, + or sub-sub-section + has a heading as the first thing in it. + These headings introduce the sections and are listed in the + contents page. +

+
+ +
+ p +

+ The paragraph element simply contains text. + Most descriptive writing is inside paragraphs. +

+
+ +
+ section +

+ The section element is just like a + chapter, except that it contains + sub-sections where a chapter would + contain sections. +

+
+ +
+ standards +

+ The standards element contains any number of + standard elements whioch specify what standards a particular + piece of code does or does not conform to. +
+ The defined values are - +

+ + <GNUstep/> + <OpenStep/> + <NotOpenStep/> + <MacOS-X/> + <NotMacOS-X/> + +
+ +
+ subsect +

+ The subsect element is just like a + section, except that it contains + sub-sub-sections where a section would + contain sub-sections. +

+
+ +
+ subsubsect +

+ The subsubsect element is just like a + sub-section, except that it contains + only a heading and zero or more + blocks. +

+
+ +
+ text +

+ This is not really an element, we simply talk about text where + we mean raw text and very simple markup such as - +

+ + br + a forced line-break + footnote + a reference to a footnote that appears in full elsewhere + label + + a piece of text marked so that it can be referred to from elsewhere. + + entry + + an invisible mark that can be referred to from elsewhere. + + ref + + text marked as a reference to elsewhere in the document. + + uref + + text marked as a reference to a hypertext URL. + + url + + a hypertext URL. + + email + + an email address. + + +
+ + + The gsdoc conversion tool