diff --git a/.hgtags b/.hgtags deleted file mode 100644 index c537c5f..0000000 --- a/.hgtags +++ /dev/null @@ -1 +0,0 @@ -6c962da1608a16051b0f4f95837425fdbf045701 start diff --git a/docbook-utils.dsl b/docbook-utils.dsl deleted file mode 100644 index 93aacde..0000000 --- a/docbook-utils.dsl +++ /dev/null @@ -1,1107 +0,0 @@ - - - -]]> - - -]]> -]> - - - - - - - - - -;;========================================================================== -;; PRINT -;;========================================================================== - -;;====================================== -;;General Options -;;====================================== - -;;Do you want to print on both sides of the paper? -(define %two-side% - #t) - -;;Do you want enumerated sections? (E.g, 1.1, 1.1.1, 1.2, etc.) -(define %section-autolabel% - #t) - -;;What is the default extension for graphics? -(define %graphic-default-extension% - "eps") - -;;Show URL links? If the text of the link and the URL are identical, -;;the parenthetical URL is suppressed. -(define %show-ulinks% - #t) - -;;Put footnotes at the bottom of the page. -(define bop-footnotes - #t) - -;Make Ulinks footnotes to stop bleeding in the edges - this increases -;'jade --> print' time tremendously keep this in mind before -;complaining! -(define %footnote-ulinks% - #f) - -;;Tex Backend on -(define tex-backend - #t) - -;;Define Line Spacing -(define %line-spacing-factor% 1.1) - -;;Define the Paragraph Style -(define para-style - (style - font-size: %bf-size% - font-weight: 'medium - font-posture: 'upright - font-family-name: %body-font-family% - line-spacing: (* %bf-size% %line-spacing-factor%))) - -(define ($object-titles-after$) - (list (normalize "figure"))) - -;;====================================== -;;Book Options -;;====================================== - - -;;Do you want a title page for a Book? -(define %generate-book-titlepage% - #t) - -;;Do you want a separate page for the title? -(define %generate-book-titlepage-on-separate-page% - #t) - -;;Generate Book TOC? -(define %generate-book-toc% - #t) - -;;Generate Book LOT for figures -(define (%generate-book-lot-list$) - (list (normalize "figure"))) - -;;What depth should the TOC generate? -;;!Only top level of appendixes! -(define (toc-depth nd) - (if (string=? (gi nd) (normalize "book")) - 3 - (if (string=? (gi nd) (normalize "appendix")) - 0 - 1))) - -;;Do you want a TOC for the element part? -(define %generate-part-toc% - #f) - -;;Do you want the part toc on the part titlepage or separate? -(define %generate-part-toc-on-titlepage% - #f) - -;;Generate Part Title Page? -(define %generate-part-titlepage% - #f) - -;;Do you want the Part intro on the part title page? -(define %generate-partintro-on-titlepage% - #t) - -;;What elements should have a LOT? -(define ($generate-book-lot-list$) - (list (normalize "equation"))) - -;;Do you want chapters enumerated? -(define %chapter-autolabel% - #t) - -;;Do you want Chapter's and Appendix's -;;to have automatic labels? -(define %chap-app-running-head-autolabel% - #t) - - -;;====================================== -;;Article Options -;;====================================== - -;;Do you want a title page for an Article? -(define %generate-article-titlepage% - #t) - -;;Generate Article TOC? -(define %generate-article-toc% - #t) - -;;Generate Article LOT for figures -(define (%generate-article-lot-list$) - (list (normalize "figure"))) - -;;Do you want a separate page for the title? -(define %generate-article-titlepage-on-separate-page% - #t) - -;;Do you want the article toc on the titlepage or separate? -(define %generate-article-toc-on-titlepage% - #t) - -;;Do you want to start new page numbers with each article? -(define %article-page-number-restart% - #f) - -;;Titlepage Separate? -(define (chunk-skip-first-element-list) - '()) - -;;Titlepage Not Separate -;(define (chunk-skip-first-element-list) -; (list (normalize "sect1") -; (normalize "section"))) - -;;====================================== -;;Columns -;;====================================== - -;;How many columns do you want? -(define %page-n-columns% - 1) - -;;How much space between columns? -(define %page-column-sep% - 0.2in) - -;;How many Columns on the titlepage? -(define %titlepage-n-columns% - 1) - -;;Balance columns? -(define %page-balance-colums% -#t) - -;;====================================== -;;Fonts -;;====================================== - -;;Defines the general size of the text in the document. normal(10), -;;presbyopic(12), and large-type(24). -(define %visual-acuity% - "normal") - -;;What font would you like for titles? -(define %title-font-family% - "Helvetica") - -;;What font would you like for the body? -(define %body-font-family% - "Palatino") - -;;What font would you like for mono-seq? -(define %mono-font-family% - "Courier New") - -;;If the base fontsize is 10pt, and '%hsize-bump-factor%' is -;; 1.2, hsize 1 is 12pt, hsize 2 is 14.4pt, hsize 3 is 17.28pt, etc -(define %hsize-bump-factor% - 1.1) - -;;What size do you want the body fonts? -(define %bf-size% - (case %visual-acuity% - (("tiny") 8pt) - (("normal") 10pt) - (("presbyopic") 12pt) - (("large-type") 24pt))) - -(define-unit em %bf-size%) - -;;====================================== -;;Margins -;;====================================== - -(define %left-right-margin% 6pi) - -;;How much indentation for the body? -(define %body-start-indent% - 4pi) - -;;How big is the left margin? (relative to physical page) -(define %left-margin% - 8pi) ;white-paper-column - -;;How big is the right margin? (relative to physical page) -(define %right-margin% - 8pi) ;white-paper-column - -;;How big do you want the margin at the top? -(define %top-margin% -(if (equal? %visual-acuity% "large-type") - 7.5pi - 6pi)) - -;;How big do you want the margin at the bottom? -(define %bottom-margin% - (if (equal? %visual-acuity% "large-type") - 7.5pi - 5pi)) - -;;Define the text width. (Change the elements in the formula rather -;;than the formula itself) -;(define %text-width% (- %page-width% (* %left-right-margin% 2))) -(define %text-width% (- %page-width% (+ %left-margin% %right-margin%))) - -;;Define the body width. (Change the elements in the formula rather -;;than the formula itself) -(define %body-width% - (- %text-width% %body-start-indent%)) - -;;Define distance between paragraphs -(define %para-sep% - (/ %bf-size% 2.0)) - -;;Define distance between block elements (figures, tables, etc.). -(define %block-sep% - (* %para-sep% 2.0)) - -;;Indent block elements? -(define %block-start-indent% - 0pt) -;0pt - -;;====================================== -;;Admon Graphics -;;====================================== - -;;Do you want admon graohics on? -(define %admon-graphics% - #f) - -;;Where are the admon graphics? -(define %admon-graphics-path% - "../images/") - -;;====================================== -;;Quadding -;;====================================== - -;;What quadding do you want by default; start, center, justify, or end? -(define %default-quadding% - 'start) - -;;What quadding for component titles(Chapter, Appendix, etc)? -(define %component-title-quadding% - 'start) - -;;What quadding for section titles? -(define %section-title-quadding% - 'start) - -;;What quadding for section sub-titles? -(define %section-subtitle-quadding% - 'start) - -;;What quadding for article title? -(define %article-title-quadding% - 'center) - -;;What quadding for article sub-titles? -(define %article-subtitle-quadding% - 'center) - -;;What quadding for division subtitles? -(define %division-subtitle-quadding% - 'start) - -;;What quadding for component subtitles? -(define %component-subtitle-quadding% - 'start) - - - - -;;====================================== -;;Paper Options -;;====================================== - -;;What size paper do you need? A4, USletter, USlandscape, or RedHat? -(define %paper-type% - "A4") - -;;Now define those paper types' width -(define %page-width% - (case %paper-type% - (("A4") 210mm) - (("USletter") 8.5in) - (("USlandscape") 11in))) - -;;Now define those paper types' height -(define %page-height% - (case %paper-type% - (("A4") 297mm) - (("USletter") 11in) - (("USlandscape") 8.5in))) - -;;====================================== -;;Functions -;;====================================== - -(define (OLSTEP) - (case - (modulo (length (hierarchical-number-recursive "ORDEREDLIST")) 4) - ((1) 1.2em) - ((2) 1.2em) - ((3) 1.6em) - ((0) 1.4em))) - -(define (ILSTEP) 1.0em) - -(define (PROCSTEP ilvl) - (if (> ilvl 1) 1.8em 1.4em)) - -(define (PROCWID ilvl) - (if (> ilvl 1) 1.8em 1.4em)) - - -(define ($comptitle$) - (make paragraph - font-family-name: %title-font-family% - font-weight: 'bold - font-size: (HSIZE 2) - line-spacing: (* (HSIZE 2) %line-spacing-factor%) - space-before: (* (HSIZE 2) %head-before-factor%) - space-after: (* (HSIZE 2) %head-after-factor%) - start-indent: 0pt - first-line-start-indent: 0pt - quadding: 'start - keep-with-next?: #t - (process-children-trim))) - -;;Callouts are confusing in Postscript... fix them. -(define %callout-fancy-bug% - #f) - - -;;By default perils are centered and dropped into a box with a really -;;big border - I have simply decreased the border thickness - -;;unfortunately it takes all this to do it - sigh. -(define ($peril$) - (let* ((title (select-elements - (children (current-node)) (normalize "title"))) - (has-title (not (node-list-empty? title))) - (adm-title (if has-title - (make sequence - (with-mode title-sosofo-mode - (process-node-list (node-list-first title)))) - (literal - (gentext-element-name - (current-node))))) - (hs (HSIZE 2))) - (if %admon-graphics% - ($graphical-admonition$) - (make display-group - space-before: %block-sep% - space-after: %block-sep% - font-family-name: %admon-font-family% - font-size: (- %bf-size% 1pt) - font-weight: 'medium - font-posture: 'upright - line-spacing: (* (- %bf-size% 1pt) %line-spacing-factor%) - (make box - display?: #t - box-type: 'border - line-thickness: .5pt - start-indent: (+ (inherited-start-indent) (* 2 (ILSTEP)) 2pt) - end-indent: (inherited-end-indent) - (make paragraph - space-before: %para-sep% - space-after: %para-sep% - start-indent: 1em - end-indent: 1em - font-family-name: %title-font-family% - font-weight: 'bold - font-size: hs - line-spacing: (* hs %line-spacing-factor%) - quadding: 'center - keep-with-next?: #t - adm-title) - (process-children)))))) - - -;;====================================== -;;Non-printing Elements -;;====================================== -(element TITLEABBREV (empty-sosofo)) -(element SUBTITLE (empty-sosofo)) -(element SETINFO (empty-sosofo)) -(element BOOKINFO (empty-sosofo)) -(element BIBLIOENTRY (empty-sosofo)) -(element BIBLIOMISC (empty-sosofo)) -(element BOOKBIBLIO (empty-sosofo)) -(element SERIESINFO (empty-sosofo)) -(element DOCINFO (empty-sosofo)) -(element ARTHEADER (empty-sosofo)) -;;(element ADDRESS (empty-sosofo)) - -;;Show comment element? -(define %show-comments% - #t) - -;;====================================== -;;Formalpara titles -;;====================================== - - -;;Change the way Formal Paragraph titles are displayed. The commented -;;out section will run the titles in the paragraphs. -(element (formalpara title) - ;(make sequence - ;font-weight: 'bold - ;($runinhead$)) - ($lowtitle$ 5 7)) - -;;====================================== -;;Inlines -;;====================================== - -(element application ($mono-seq$)) -(element command ($bold-seq$)) -(element filename ($mono-seq$)) -(element function ($mono-seq$)) -(element guibutton ($bold-seq$)) -(element guiicon ($bold-seq$)) -(element guilabel ($italic-seq$)) -(element guimenu ($bold-seq$)) -(element guimenuitem ($bold-seq$)) -(element hardware ($bold-mono-seq$)) -(element keycap ($bold-seq$)) -(element literal ($mono-seq$)) -(element parameter ($italic-mono-seq$)) -(element prompt ($mono-seq$)) -(element symbol ($charseq$)) -(element emphasis ($italic-seq$)) - - - - - - - - - - -;; this is necessary because right now jadetex does not understand -;; symbolic entities, whereas things work well with numeric entities. -(declare-characteristic preserve-sdata? - "UNREGISTERED::James Clark//Characteristic::preserve-sdata?" - #f) - - -;;========================= -;;Header HTML 4.0.1 -;;========================= - -(define %html-pubid% "-//W3C//DTD HTML 4.01//EN") - -;;========================= -;;Common Stuff -;;========================= - -;;Should there be a link to the legalnotice? -(define %generate-legalnotice-link% - #t) - -;;What graphics extensions allowed? -(define %graphic-extensions% -'("gif" "png" "jpg" "jpeg" "tif" "tiff" "eps" "epsf" )) - -;;What mediaobject extensions allowed? -(define acceptable-mediaobject-extensions -'("gif" "png" "jpg" "jpeg" "tif" "tiff" "eps" "epsf" )) - -;;What is the default extension for images? -(define %graphic-default-extension% "png") - -;;Use element ids as filenames? -(define %use-id-as-filename% - #t) - - -;;========================= -;;Book Stuff -;;========================= - -;;Do you want a TOC for Books? -(define %generate-book-toc% - #t) - -;;What depth should the TOC generate? -;;!Only top level of appendixes! -(define (toc-depth nd) - (if (string=? (gi nd) (normalize "book")) - 3 - (if (string=? (gi nd) (normalize "appendix")) - 0 - 1))) - -;;What elements should have an LOT? -(define ($generate-book-lot-list$) - (list (normalize "figure"))) - -;;Do you want a title page for your Book? -(define %generate-book-titlepage% -#t) - -;;========================= -;;Part Stuff -;;========================= - -;;Should parts have TOCs? -(define %generate-part-toc% - #t) - -;;Should part TOCs be on their titlepages? -(define %generate-part-toc-on-titlepage% - #t) - -;;Do you want a title page for your part? -(define %generate-part-titlepage% - #t) - -;;Should the Part intro be on the part title page? -(define %generate-partintro-on-titlepage% - #t) - -(define %para-autolabel% - #t) - -;;======================== -;;Chapter Stuff -;;======================= - -;;No TOCs in Chapters -(define $generate-chapter-toc$ - (lambda () - #f)) - -;;========================= -;;Navigation -;;========================= - -;;Should there be navigation at top? -(define %header-navigation% - #t) - -;;Should there be navigation at bottom? -(define %footer-navigation% - #t) - -;;Use tables to create the navigation? -(define %gentext-nav-use-tables% - #t) - -;;If tables are used for navigation, -;;how wide should they be? -(define %gentext-nav-tblwidth% -"100%") - -;;Add arrows to navigation (comment these -;;out if you want admon graphics here) -(define (gentext-en-nav-prev prev) - (make sequence (literal "<<< Previous"))) - -;;Add arrows to navigation (comment these -;;out if you want admon graphics here) -(define (gentext-en-nav-next next) - (make sequence (literal "Next >>>"))) - - -;;========================= -;;Tables and Lists -;;========================= - -;;Should Variable lists be tables? -(define %always-format-variablelist-as-table% - #f) - -;;What is the length of the 'Term' in a variablelist? -(define %default-variablelist-termlength% - 20) - -;;When true | If the terms are shorter than -;;the termlength above then the variablelist -;;will be formatted as a table. -(define %may-format-variablelist-as-table% -#f) - -;;This overrides the tgroup definition -;;(copied from 1.20, dbtable.dsl). -;;It changes the table background color, -;;cell spacing and cell padding. -;;This is based on gtk-doc additions - thanks! - -(element tgroup - (let* ((wrapper (parent (current-node))) - (frameattr (attribute-string (normalize "frame") wrapper)) - (pgwide (attribute-string (normalize "pgwide") wrapper)) - (footnotes (select-elements (descendants (current-node)) - (normalize "footnote"))) - (border (if (equal? frameattr (normalize "none")) - '(("BORDER" "0")) - '(("BORDER" "1")))) - (bgcolor '(("BGCOLOR" "#E0E0E0"))) - (width (if (equal? pgwide "1") - (list (list "WIDTH" ($table-width$))) - '())) - (head (select-elements (children (current-node)) (normalize "thead"))) - (body (select-elements (children (current-node)) (normalize "tbody"))) - (feet (select-elements (children (current-node)) (normalize "tfoot")))) - (make element gi: "TABLE" - attributes: (append - border - width - bgcolor - '(("CELLSPACING" "0")) - '(("CELLPADDING" "4")) - (if %cals-table-class% - (list (list "CLASS" %cals-table-class%)) - '())) - (process-node-list head) - (process-node-list body) - (process-node-list feet) - (make-table-endnotes)))) - -;;=================== -;; Admon Graphics -;;=================== - -;;Should Admon Graphics be used? -(define %admon-graphics% - #f) - -;;Where are those admon graphics? -(define %admon-graphics-path% - "./stylesheet-images/") - -;;Given an admonition node, returns the -;;name of the graphic that should -;;be used for that admonition. -;;Define admon graphics usage -;;NOTE these will change to pngs -;;soon in the GDP when Tigert gets -;;the time to make special ones for us! -(define ($admon-graphic$ #!optional (nd (current-node))) - (cond ((equal? (gi nd) (normalize "tip")) - (string-append %admon-graphics-path% "tip.gif")) - ((equal? (gi nd) (normalize "note")) - (string-append %admon-graphics-path% "note.gif")) - ((equal? (gi nd) (normalize "important")) - (string-append %admon-graphics-path% "important.gif")) - ((equal? (gi nd) (normalize "caution")) - (string-append %admon-graphics-path% "caution.gif")) - ((equal? (gi nd) (normalize "warning")) - (string-append %admon-graphics-path% "warning.gif")) - (else (error (string-append (gi nd) " is not an admonition."))))) - -;;Given an admonition node, returns -;;the width of the graphic that will -;;be used for that admonition. -(define ($admon-graphic-width$ #!optional (nd (current-node))) - "25") - -;;========================= -;;Labels -;;========================= - -;;Enumerate Chapters? -(define %chapter-autolabel% - #t) - -;;Enumerate Sections? -(define %section-autolabel% - #t) - -;;========================= -;; HTML Attributes -;;========================= - -;;What attributes should be hung off -;;of 'body'? -(define %body-attr% - (list - (list "BGCOLOR" "#FFFFFF") - (list "TEXT" "#000000") - (list "LINK" "#0000FF") - (list "VLINK" "#840084") - (list "ALINK" "#0000FF"))) - -;;Default extension for filenames? -(define %html-ext% - ".html") - -;;Use a CSS stylesheet? -;;Which one? Should work on -;;this one soon -;(define %stylesheet% -; "./gnome.css") - -;;Use it -;(define %stylesheet-type% -;"text/css") - - -;;======================== -;;Title Pages for Books -;;======================= - -(define (book-titlepage-recto-elements) - (list (normalize "title") - (normalize "subtitle") - (normalize "corpauthor") - (normalize "authorgroup") - (normalize "author") - (normalize "orgname") - (normalize "graphic") - (normalize "copyright") - (normalize "revhistory") - (normalize "legalnotice") - (normalize "releaseinfo") - (normalize "publisher") - (normalize "isbn"))) - -;;======================== -;;Title Pages for Articles -;;======================== - -;;Should Articles have a TOC? -(define %generate-article-toc% - #t) - -;;Generate Article LOT for figures -(define (%generate-article-lot-list$) - (list (normalize "figure"))) - -;;Which elements should appear -;;on title page? -(define (article-titlepage-recto-elements) - (list (normalize "title") - (normalize "subtitle") - (normalize "authorgroup") - (normalize "copyright") - (normalize "legalnotice") - (normalize "abstract"))) - -;;How should elements on title page look? -(mode article-titlepage-recto-mode - -;;Author name is too big - change it! - (element author - (let ((author-name (author-string)) - (author-affil (select-elements (children (current-node)) - (normalize "affiliation")))) - (make sequence - (make element gi: "H4" - attributes: (list (list "CLASS" (gi))) - (make element gi: "A" - attributes: (list (list "NAME" (element-id))) - (literal author-name))) - (process-node-list author-affil)))) - -;;Address? - (element address - (make sequence - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - (process-children)))) - -;;Get rid of spam-producing "mailto" links -;;and get rid of email indentation - (element email - (make sequence - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - (process-children)))) - -;;Point Abstract to custom table function -;;(See $dcm-abstract-object$ below. For default -;;use $semiformal-object$ - (element abstract - (make element gi: "DIV" - ($dcm-abstract-object$))) - - (element (abstract title) (empty-sosofo)) - -;;subtitle sizing -(element subtitle - (make element gi: "H4" - attributes: (list (list "CLASS" (gi))) - (process-children-trim)))) - -;;================= -;; INLINES -;;================= - -;Define my own series of fonts for various elements -(element application ($mono-seq$)) -(element command ($bold-seq$)) -(element filename ($mono-seq$)) -(element function ($mono-seq$)) -(element guibutton ($bold-seq$)) -(element guiicon ($bold-seq$)) -(element guilabel ($bold-mono-seq$)) -(element guimenu ($bold-seq$)) -(element guimenuitem ($bold-seq$)) -(element guisubmenu ($bold-seq$)) -(element hardware ($bold-mono-seq$)) -(element keycap ($bold-seq$)) -(element literal ($mono-seq$)) -(element parameter ($italic-mono-seq$)) -(element prompt ($mono-seq$)) -(element symbol ($charseq$)) -(element emphasis ($italic-seq$)) - -;;Show comment element? -(define %show-comments% - #t) - -;;==================== -;; General Formatting -;;==================== - -;;Formal Paras are ugly by default! -;;Make the title run in - otherwise -;;you should use a sect! -(element formalpara - (make element gi: "DIV" - attributes: (list - (list "CLASS" (gi))) - (make element gi: "P" - (process-children)))) - -;;This is the old one -;(element (formalpara title) -;($lowtitle$ 5)) - -;;This is the new one -(element (formalpara title) - (make element gi: "B" - ($runinhead$))) - -;;Make captions come after objects in the list -(define ($object-titles-after$) - (list (normalize "figure"))) - - -;; Handle qanda labelling with Q: A: -(define (qanda-defaultlabel) - (normalize "qanda")) - -;;From FreeBSD Sheets (Thanks!) Display Q and A in bigger bolder fonts - -(element question - (let* ((chlist (children (current-node))) - (firstch (node-list-first chlist)) - (restch (node-list-rest chlist))) - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - (make element gi: "P" - (make element gi: "BIG" - (make element gi: "A" - attributes: (list - (list "NAME" (element-id))) - (empty-sosofo)) - (make element gi: "B" - (literal (question-answer-label - (current-node)) " ") - (process-node-list (children firstch))))) - (process-node-list restch)))) - -;;Literal Elements - -;;Indent Literal layouts? -(define %indent-literallayout-lines% - #f) - -;;Indent Programlistings? -(define %indent-programlisting-lines% - #f) - -;;Number lines in Programlistings? -(define %number-programlisting-lines% - #f) - -;;Should verbatim items be 'shaded' with a table? -(define %shade-verbatim% - #t) - -;;Define shade-verbatim attributes -(define ($shade-verbatim-attr$) - (list - (list "BORDER" "0") - (list "BGCOLOR" "#E0E0E0") - (list "WIDTH" ($table-width$)))) - -;;================== -;; Refentry -;;================== - -(element (group arg) - (let ((choice (attribute-string (normalize "choice"))) - (rep (attribute-string (normalize "rep")))) - (make sequence - (if (not (first-sibling? (current-node))) - (literal %arg-or-sep%) - (empty-sosofo)) - (process-children) - (cond - ((equal? rep (normalize "repeat")) (literal %arg-rep-repeat-str%)) - ((equal? rep (normalize "norepeat")) (literal %arg-rep-norepeat-str%)) - (else (literal %arg-rep-def-str%)))))) - -;;=================== -;; Entities -;;=================== - -;;Netscape doesn't handle trademark -;;entity right at all!! Get rid of it. -;;Make a TM in a superscipt font. -(element trademark - (make sequence - (process-children) - (make element gi: "sup" - (literal "TM")))) - - -;;=================== -;; New Definitions -;;================== - -(define ($dcm-abstract-object$) - (make element gi: "TABLE" - attributes: '(("BORDER" "0") - ("BGCOLOR" "#E0E0E0") - ("WIDTH" "50%") - ("CELLSPACING" "0") - ("CELLPADDING" "0") - ("ALIGN" "CENTER")) - (make element gi: "TR" - (make element gi: "TD" - attributes: '(("VALIGN" "TOP")) - (make element gi: "B" - (literal "Abstract")))) - (make element gi: "TR" - (make element gi: "TD" - attributes: '(("VALIGN" "TOP")) - (process-children))))) - -;;Redefine Titlepage Separator on Articles - -(define (article-titlepage-separator side) - (make empty-element gi: "HR" - attributes: '(("WIDTH" "75%") - ("ALIGN" "CENTER") - ("COLOR" "#000000") - ("SIZE" "1")))) - - - - -(define (chunk-element-list) - (list (normalize "preface") - (normalize "chapter") - (normalize "appendix") - (normalize "article") - (normalize "glossary") - (normalize "bibliography") - (normalize "index") - (normalize "colophon") - (normalize "setindex") - (normalize "reference") - (normalize "refentry") - (normalize "part") - (normalize "sect1") - (normalize "section") - (normalize "book") ;; just in case nothing else matches... - (normalize "set") ;; sets are definitely chunks... - )) - -;;Do you want Callouts to be graphics? -(define %callout-graphics% -#f) - - -;;Make Callout graphics PNGs -(define %callout-graphics-path% - "./imagelib/callouts/") - - ;; Redefine $callout-bug$ to support the %callout-graphic-ext% - ;; variable. - (define ($callout-bug$ conumber) - (let ((number (if conumber (format-number conumber "1") "0"))) - (if conumber - (if %callout-graphics% - (if (<= conumber %callout-graphics-number-limit%) - (make empty-element gi: "IMG" - attributes: (list (list "SRC" - (root-rel-path - (string-append - %callout-graphics-path% - number - %callout-graphics-ext%))) - (list "HSPACE" "0") - (list "VSPACE" "0") - (list "BORDER" "0") - (list "ALT" - (string-append - "(" number ")")))) - (make element gi: "B" - (literal "(" (format-number conumber "1") ")"))) - (make element gi: "B" - (literal "(" (format-number conumber "1") ")"))) - (make element gi: "B" - (literal "(??)"))))) - - - - - - - diff --git a/event/Event.api b/historical/Event.api similarity index 100% rename from event/Event.api rename to historical/Event.api diff --git a/membership/oc_membership.h b/historical/oc_membership.h similarity index 100% rename from membership/oc_membership.h rename to historical/oc_membership.h diff --git a/ra/1.0/ra-api.ng b/ra/1.0/ra-api.rng similarity index 100% copy from ra/1.0/ra-api.ng copy to ra/1.0/ra-api.rng diff --git a/ra/1.1/Makefile b/ra/1.1/Makefile new file mode 100644 index 0000000..2cebe61 --- /dev/null +++ b/ra/1.1/Makefile @@ -0,0 +1,19 @@ +# Basic DocBook mangling makefile. +# +# + +BASENAME=resource-agent-api + +.PHONY: all clean + +%.html: %.md + pandoc -f markdown -o $@ $^ + +%.pdf: %.md + pandoc -f markdown -o $@ $^ + +all: $(BASENAME).pdf $(BASENAME).html + +clean: + rm -f $(BASENAME).pdf $(BASENAME).html + diff --git a/ra/1.0/ra-api.ng b/ra/1.1/ra-api.rng similarity index 100% rename from ra/1.0/ra-api.ng rename to ra/1.1/ra-api.rng diff --git a/ra/1.1/ra-metadata-example.xml b/ra/1.1/ra-metadata-example.xml new file mode 100644 index 0000000..bb7e38d --- /dev/null +++ b/ra/1.1/ra-metadata-example.xml @@ -0,0 +1,105 @@ + + + + + + +1.1 + + + + + + + + + +The resource name is the directory where the filesystem will be actually +mounted. Please make sure it exists. + + + +Mountpoint + + + + + + + + +When mounting a filesystem on a specific mountpoint, you have to specify which +device should be mounted; this will usually be similiar to /dev/sda1 or +/dev/volumegroup/logicalvolume when using LVM. + +Device to be mounted + + + + + +You should chose a journaled filesystem for the shared storage to ensure that +the filesystem remains consistent and that it can be mounted without an +expensive fsck run; recommendations include reiserfs, ext3 and XFS. + +Type of the filesystem + + + + + +The mount options used for mounting a filesystem; normally this is set to +defaults, but you may want to modify this if you require a read-only +mount or something similar. + +Mount options for this filesystem + + + + + + + + + + + + + + + + + + + + + + + + +403 + + + diff --git a/ra/1.1/resource-agent-api.md b/ra/1.1/resource-agent-api.md new file mode 100644 index 0000000..ff4c6d2 --- /dev/null +++ b/ra/1.1/resource-agent-api.md @@ -0,0 +1,498 @@ +**DRAFT - DRAFT - DRAFT** + +**JOIN THE developers@clusterlabs.org MAILING LIST AND FOLLOW PULL REQUESTS +AT https://github.com/ClusterLabs/OCF-spec/ TO DISCUSS CHANGES** + +# Open Clustering Framework Resource Agent API + +Editor: Lars Marowsky-Brée + +URL: https://github.com/ClusterLabs/OCF-spec/blob/master/ra/1.1/resource-agent-api.md + +## License + + Copyright (c) 2002, 2018 Lars Marowsky-Brée. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 or + any later version published by the Free Software Foundation; with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A + copy of the license can be found at http://www.gnu.org/licenses/fdl.txt. + +## Abstract + +Resource Agents (RA) are the middle layer between the Resource Manager +(RM) and the actual resources being managed. They aim to integrate the +resource type with the RM without any modifications to the actual +resource provider itself, by encapsulating it carefully and providing +generic methods (actions) to operate on them. + +The RAs are obviously very specific to the resource type they operate +on, however there is no reason why they should be specific to a +particular RM. + +The API described in this document should be general enough that a +compliant Resource Agent can be used by all existing resource managers / +switch-over systems who chose to implement this API either exclusively +or in addition to their existing one. + + +### Scope + +This document describes a common API for the RM to call the RAs so the +pool of available RAs can be shared by the different clustering +solutions. + +It does NOT define any libraries or helper functions which RAs might share +with regard to common functionality like external command execution, cluster +logging et cetera, as these are NOT specific to RA and are defined in the +respective standards. + + +### API version described + +This document currently describes version 1.1 of the API. + + +## Terms used in this document + +### "Resource" + +A single physical or logical entity that provides a service to clients or +other resources. For example, a resource can be a single disk volume, a +particular network address, or an application such as a web server. A resource +is generally available for use over time on two or more nodes in a cluster, +although it usually can be allocated to only one node at any given time. + +Resources are identified by a name that must be unique to the particular +resource type. This is any name chosen by the administrator to identify +the resource instance and passed to the RA as a special environment +variable. + +A resource may also have instance parameters which provide additional +information required for Resource Agent to control the resource. + + +### "Resource types" + +A resource type represents a set of resources which share a common set of +instance parameters and a common set of actions which can be performed on +resource of the given type. + +The resource type name is chosen by the provider of the RA. + + +### "Resource agent" + +A RA provides the actions ("member functions") for a given type of +resources; by providing the RA with the instance parameters, it is used +to control a specific resource. + +They are usually implemented as shell scripts, but the API described here does +not require this. + +Although this is somewhat similar to LSB init scripts, there are some +differences explained below. + + +### "Instance parameters" + +Instance parameters are the attributes which describe a given resource +instance. It is recommended that the implementor minimize the set of +instance parameters. + +The meta data allows the RA to flag one or more instance parameters as +`unique`. This is a hint to the RM or higher level configuration tools +that the combination of these parameters must be unique to the given +resource type. + +An instance parameter has a given name and value. They are both case +sensitive and must satisfy the requirements of POSIX environment +name/value combinations. + + +## API + +### API Version Numbers + +The version number is of the form `x.y`, where `x` and `y` are positive +numbers greater or equal to zero. `x` is referred to as the "major" +number, and `y` as the "minor" number. + +The major number must be increased if a _backwards incompatible_ change is +made to the API. A major number mismatch between the RA and the RM must be +reported as an error by both sides. + +The minor number must be increased if _any_ change at all is made to the +API. If the major is increased, the minor number should be reset to +zero. The minor number can be used by both sides to see whether a +certain additional feature is supported by the other party. + + +### Paths + +The Resource Agents are located in subdirectories under +`/usr/ocf/resource.d`. + +The subdirectories allow the installation of multiple RAs for the same +type, but from different vendors or package versions. + +The filename within the directories equals the resource type name +provided by the RA and may be a link to the real location. + +Example directory structure: + + FailSafe -> FailSafe-1.1.0/ + FailSafe-1.0.4/ + FailSafe-1.1.0/ + heartbeat -> heartbeat-1.1.2/ + heartbeat-1.1.2/ + heartbeat-1.1.2/IPAddr + heartbeat-1.1.2/IP -> IPAddr + +How the RM choses an agent for a specific resource type name from the +available set is implementation specific. + + +### Execution syntax + +After the RM has identified the executable to call, the RA will be +called with the requested action as its sole argument. + +To allow for further extensions, the RA shall ignore all other +arguments. + + +### Resource Agent actions + +A RA must be able to perform the following actions on a given resource +instance on request by the RM; additional actions may be supported by +the script for example for LSB compliance. + +The actions are all required to be idempotent. Invoking any operation +twice - in particular, the start and stop actions - shall succeed and +leave the resource instance in the requested state. + +In general, a RA should not assume it is the only RA of its type running +at any given time because the RM might start several RA instances for +multiple independent resource instances in parallel. + +_Mandatory_ actions must be supported; _optional_ operations must be +advertised in the meta data if supported. If the RM tries to call a +unsupported action the RA shall return an error as defined below. + + +- `start` + + Mandatory. + + This brings the resource instance online and makes it available for + use. It should NOT terminate before the resource instance has either + been fully started or an error has been encountered. + + It may try to implement recovery actions for certain cases of startup + failures. + + `start` must succeed if the resource instance is already running. + + `start` must return an error if the resource instance is not fully + started. + +- `stop` + + Mandatory. + + This stops the resource instance. After the `stop` command has + completed, no component of the resource shall remain active and it + must be possible to start it on the same node or another node or an + error must be returned. + + The `stop` request by the RM includes the authorization to bring down the + resource even by force as long data integrity is maintained; breaking + currently active transactions should be avoided, but the request to offline + the resource has higher priority than this. If this is not possible, + the RA shall return an error to allow higher level recovery. + + The `stop` action should also perform clean-ups of artifacts like leftover + shared memory segments, semaphores, IPC message queues, lock files etc. + + `stop` must succeed if the resource is already stopped. + + `stop` must return an error if the resource is not fully stopped. + +- `monitor` + + Mandatory. + + Checks and returns the current status of the resource instance. The + thoroughness of the check is further influenced by the weight of the + check, which is further explained under **Action specific extensions**.. + + It is accepted practice to have additional instance parameters which + are not strictly required to identify the resource instance but are + needed to monitor it or customize how intrusive this check is allowed + to be. + + Note that `monitor` shall also return a well defined error code (see + below) for stopped instances, ie before `start` has ever been + invoked. + +- `recover` + + Optional. + + A special case of the `start` action, this should try to recover a resource + locally. + + It is recommended that this action is not advertised unless it is + advantageous to use when compared to a stop/start operation. + + If this is not supported, it may be mapped to a stop/start action by + the RM. + + An example includes "recovering" an IP address by moving it to another + interface; this is much less costly than initiating a full resource group + fail over to another node. + +- `reload` + + Optional. + + Notifies the resource instance of a configuration change external to + the instance parameters; it should reload the configuration of the + resource instance without disrupting the service. + + It is recommended that this action is not advertised unless it is + advantageous to use when compared to a stop/start operation. + + If this is not supported, it may be mapped to a stop/start action by + the RM. + +- `meta-data` + + Mandatory. + + Returns the resource agent meta data via stdout. + +- `validate-all` + + Optional. + + Validate the instance parameters provided. + + Perform a syntax check and if possible, a semantic check on the + instance parameters. + + +### Parameter passing + +The instance parameters and some additional attributes are passed in via the +environment; this has been chosen because it does not reveal the parameters to +an unprivileged user on the same system and environment variables can be +easily accessed by all programming languages and shell scripts. + +The entire environment variable name space starting with `OCF_` is considered to +be reserved for OCF use. + + +#### Syntax for instance parameters + +They are directly converted to environment variables; the name is prefixed +with `OCF_RESKEY_`. + +The instance parameter `force` with the value `yes` thus becomes +`OCF_RESKEY_force=yes` in the environment. + +See the terms section on instance parameters for a more formal explanation. + + +#### Global OCF attributes + +Currently, the following additional environment variables are defined: + +* `OCF_RA_VERSION_MAJOR` +* `OCF_RA_VERSION_MINOR` + + Version number of the OCF Resource Agent API. If the script does + not support this revision, it should report an error. + + See **API Version Numbers** for an explanation of the versioning + scheme used. The version number is split into two numbers for ease + of use in shell scripts. + + These two may be used by the RA to determine whether it is run under + an OCF compliant RM. + + Example: + + ``` + OCF_RA_VERSION_MAJOR=1 + OCF_RA_VERSION_MINOR=0 + ``` + +* `OCF_ROOT` + + Referring to the root of the OCF directory hierarchy. + + Example: `OCF_ROOT=/usr/ocf` + +* `OCF_RESOURCE_INSTANCE` + + The name of the resource instance. + +* `OCF_RESOURCE_TYPE` + + The name of the resource type being operated on. + +### Action specific extensions + +These environment variables are not required for all actions, but only +supported by some. + +#### Parameters specific to the 'monitor' action + +- `OCF_CHECK_LEVEL` + + - `0` + + The most lightweight check possible, which should not + have an impact on the QoS. + + Example: Check for the existence of the process. + + - `10` + + A medium weight check, expected to be called multiple + times per minute, which should not have a noticeable + impact on the QoS. + + Example: Send a request for a static page to a + webserver. + + - `20` + + A heavy weight check, called infrequently, which may + impact system or service performance. + + Example: An internal consistency check to verify service + integrity. + +Service must remain available during all of these operation. +All other number are reserved. + +It is recommended that if a requested level is not implemented, +the RA should perform the next lower level supported. + + +### Exit status codes + +These exit status codes are the ones documented in the LSB 1.1.0 +specification, with additional explanations of how they shall be used by +RAs. In general, all non-zero status codes shall indicate failure in +accordance to the best current practices. + +#### All operations + +- `0` + + No error, action succeeded completely + +- `1` + + Generic or unspecified error (current practice) + The "monitor" operation shall return this for a crashed, hung or + otherwise non-functional resource. + +- `2` + + Invalid or excess argument(s) + Likely error code for validate-all, if the instance parameters + do not validate. Any other action is free to also return this + exit status code for this case. + +- `3` + + Unimplemented feature (for example, "reload") + +- `4` + + User had insufficient privilege + +- `5` + + Program is not installed + +- `6` + + Program is not configured + +- `7` + + Program is not running + + Note: This is not the error code to be returned by a successful + "stop" operation. A successful "stop" operation shall return 0. + The "monitor" action shall return this value only for a + _cleanly_ stopped resource. If in doubt, it should return 1. + +- `8-99` + + Reserved for future LSB use + +- `100-149` + + Reserved for distribution use + +- `150-199` + + Reserved for application use + +- `200-254` + + Reserved + +## Relation to the LSB + +It is required that the current LSB spec is fully supported by the system. + +The API tries to make it possible to have RA function both as a normal LSB +init script and a cluster-aware RA, but this is not required functionality. +The RAs could however use the helper functions defined for LSB init scripts. + + +## RA meta data + +### Format + +The API has the following requirements which are not fulfilled by the +LSB way of embedding meta data into the beginning of the init scripts: + +- Independent of the language the RA is actually written in, +- Extensible, +- Structured, +- Easy to parse from a variety of languages. + +This is why the API uses simple XML to describe the RA meta data. The +DTD for this API can be found at [this location](http://www.opencf.org/standards/ra-api-1.dtd). + +### Semantics + +An example of a valid meta data output is provided in +`ra-metadata-example.xml`. + +## To-do list + +- Move the terminology definitions out into a separate document + common to all OCF work. +- An interface where the RA asynchronously informs the RM of + failures is planned but not defined yet. + +## Contributors + +- James Bottomley +- Greg Freemyer +- Simon Horman +- Ragnar Kjørstad +- Lars Marowsky-Brée +- Alan Robertson +- Yixiong Zou diff --git a/ra/license.FDL-1_2 b/ra/license.FDL-1_2 new file mode 100644 index 0000000..68d93f4 --- /dev/null +++ b/ra/license.FDL-1_2 @@ -0,0 +1,397 @@ + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/licenses/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/ra/next/ra-api.ng b/ra/next/ra-api.rng similarity index 100% rename from ra/next/ra-api.ng rename to ra/next/ra-api.rng