diff --git a/ChangeLog b/ChangeLog index 5f3086df..49e15a3d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +Wed Mar 19 21:58:47 CET 2003 Daniel Veillard + + * valid.c xmlschemastypes.c: attempt to cope with ID/IDREF(S) + declared both in the DTD and in the Schemas + * relaxng.c: more debug, added a big optimization for + * test/relaxng/testsuite.xml: augmented the testsuite + * test/relaxng/ result/relaxng: added the RelaxNG spec and a + DocBook example to the regression tests + Wed Mar 19 11:34:10 CET 2003 Daniel Veillard * check-xsddata-test-suite.py: cosmetic change for output diff --git a/relaxng.c b/relaxng.c index 40779036..beb11bb5 100644 --- a/relaxng.c +++ b/relaxng.c @@ -6,7 +6,6 @@ * Daniel Veillard */ -#define FS /** * TODO: * - error reporting @@ -131,6 +130,7 @@ typedef enum { #define IS_NULLABLE 1 #define IS_NOT_NULLABLE 2 #define IS_INDETERMINIST 4 +#define IS_MIXED 8 struct _xmlRelaxNGDefine { xmlRelaxNGType type; /* the type of definition */ @@ -228,6 +228,7 @@ struct _xmlRelaxNGParserCtxt { #define FLAGS_IGNORABLE 1 #define FLAGS_NEGATIVE 2 +#define FLAGS_MIXED_CONTENT 4 /** * xmlRelaxNGInterleaveGroup: @@ -795,7 +796,6 @@ xmlRelaxNGNewStates(xmlRelaxNGValidCtxtPtr ctxt, int size) { xmlRelaxNGStatesPtr ret; -#ifdef FS if ((ctxt != NULL) && (ctxt->freeState != NULL) && (ctxt->freeStatesNr > 0)) { @@ -804,7 +804,6 @@ xmlRelaxNGNewStates(xmlRelaxNGValidCtxtPtr ctxt, int size) ret->nbState = 0; return(ret); } -#endif if (size < 16) size = 16; ret = (xmlRelaxNGStatesPtr) xmlMalloc(sizeof(xmlRelaxNGStates) + @@ -922,7 +921,6 @@ xmlRelaxNGFreeStates(xmlRelaxNGValidCtxtPtr ctxt, { if (states == NULL) return; -#ifdef FS if ((ctxt != NULL) && (ctxt->freeStates == NULL)) { ctxt->freeStatesMax = 40; ctxt->freeStatesNr = 0; @@ -953,10 +951,6 @@ xmlRelaxNGFreeStates(xmlRelaxNGValidCtxtPtr ctxt, } else { ctxt->freeStates[ctxt->freeStatesNr++] = states; } -#else - xmlFree(states->tabState); - xmlFree(states); -#endif } /** @@ -1555,7 +1549,7 @@ xmlRelaxNGValidErrorPush(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGValidErr err, return (0); } } - if ((ctxt->err != NULL) && + if ((ctxt->err != NULL) && (ctxt->state != NULL) && (ctxt->err->node == ctxt->state->node) && (ctxt->err->err == err)) return(ctxt->errNr); @@ -1601,9 +1595,11 @@ xmlRelaxNGValidErrorPop(xmlRelaxNGValidCtxtPtr ctxt) ctxt->err = NULL; cur = &ctxt->errTab[ctxt->errNr]; if (cur->flags & ERROR_IS_DUP) { - xmlFree((xmlChar *)cur->arg1); + if (cur->arg1 != NULL) + xmlFree((xmlChar *)cur->arg1); cur->arg1 = NULL; - xmlFree((xmlChar *)cur->arg2); + if (cur->arg2 != NULL) + xmlFree((xmlChar *)cur->arg2); cur->arg2 = NULL; cur->flags = 0; } @@ -2625,10 +2621,7 @@ static int xmlRelaxNGElementMatch(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGDefinePtr define, xmlNodePtr elem); -#define IS_BLANK_NODE(n) \ - ((((n)->type == XML_TEXT_NODE) || \ - ((n)->type == XML_CDATA_SECTION_NODE)) && \ - (xmlRelaxNGIsBlank((n)->content))) +#define IS_BLANK_NODE(n) (xmlRelaxNGIsBlank((n)->content)) /** * xmlRelaxNGIsNullable: @@ -3455,6 +3448,7 @@ xmlRelaxNGComputeInterleaves(xmlRelaxNGDefinePtr def, int i,j,ret; int nbgroups = 0; int nbchild = 0; + int is_mixed = 0; /* * Don't run that check in case of error. Infinite recursion @@ -3487,6 +3481,8 @@ xmlRelaxNGComputeInterleaves(xmlRelaxNGDefinePtr def, xmlMalloc(sizeof(xmlRelaxNGInterleaveGroup)); if (groups[nbgroups] == NULL) goto error; + if (cur->type == XML_RELAXNG_TEXT) + is_mixed++; groups[nbgroups]->rule = cur; groups[nbgroups]->defs = xmlRelaxNGGetElements(ctxt, cur, 0); groups[nbgroups]->attrs = xmlRelaxNGGetElements(ctxt, cur, 1); @@ -3534,6 +3530,8 @@ xmlRelaxNGComputeInterleaves(xmlRelaxNGDefinePtr def, * and save the partition list back in the def */ def->data = partitions; + if (is_mixed != 0) + def->flags |= IS_MIXED; return; error: @@ -6836,7 +6834,8 @@ xmlRelaxNGSkipIgnored(xmlRelaxNGValidCtxtPtr ctxt ATTRIBUTE_UNUSED, (node->type == XML_PI_NODE) || (((node->type == XML_TEXT_NODE) || (node->type == XML_CDATA_SECTION_NODE)) && - (IS_BLANK_NODE(node))))) { + ((ctxt->flags & FLAGS_MIXED_CONTENT) || + (IS_BLANK_NODE(node)))))) { node = node->next; } return(node); @@ -7529,6 +7528,7 @@ xmlRelaxNGValidateInterleave(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGDefinePtr define) { int ret = 0, i, nbgroups, left; int errNr = ctxt->errNr; + int oldflags; xmlRelaxNGValidStatePtr oldstate; xmlRelaxNGPartitionPtr partitions; @@ -7544,6 +7544,34 @@ xmlRelaxNGValidateInterleave(xmlRelaxNGValidCtxtPtr ctxt, VALID_ERR(XML_RELAXNG_ERR_INTERNODATA); return(-1); } + /* + * Optimizations for MIXED + */ + oldflags = ctxt->flags; + if (define->flags & IS_MIXED) { + ctxt->flags |= FLAGS_MIXED_CONTENT; + if (nbgroups == 2) { + /* + * this is a pure case + */ + if (ctxt->state != NULL) + ctxt->state->seq = xmlRelaxNGSkipIgnored(ctxt, + ctxt->state->seq); + if (partitions->groups[0]->rule->type == XML_RELAXNG_TEXT) + ret = xmlRelaxNGValidateDefinition(ctxt, + partitions->groups[1]->rule); + else + ret = xmlRelaxNGValidateDefinition(ctxt, + partitions->groups[0]->rule); + if (ret == 0) { + if (ctxt->state != NULL) + ctxt->state->seq = xmlRelaxNGSkipIgnored(ctxt, + ctxt->state->seq); + } + ctxt->flags = oldflags; + return(ret); + } + } /* * Build arrays to store the first and last node of the chain @@ -7673,6 +7701,7 @@ xmlRelaxNGValidateInterleave(xmlRelaxNGValidCtxtPtr ctxt, } done: + ctxt->flags = oldflags; /* * builds the next links chain from the prev one */ @@ -7942,6 +7971,14 @@ xmlRelaxNGValidateState(xmlRelaxNGValidCtxtPtr ctxt, */ if (node->_private == define) { ctxt->state->seq = xmlRelaxNGSkipIgnored(ctxt, node->next); + if (ctxt->errNr != 0) { + while ((ctxt->err != NULL) && + (((ctxt->err->err == XML_RELAXNG_ERR_ELEMNAME) && + (xmlStrEqual(ctxt->err->arg2, node->name))) || + (ctxt->err->err == XML_RELAXNG_ERR_NOELEM) || + (ctxt->err->err == XML_RELAXNG_ERR_NOTELEM))) + xmlRelaxNGValidErrorPop(ctxt); + } break; } @@ -7963,6 +8000,10 @@ xmlRelaxNGValidateState(xmlRelaxNGValidCtxtPtr ctxt, } errNr = ctxt->errNr; + oldflags = ctxt->flags; + if (ctxt->flags & FLAGS_MIXED_CONTENT) { + ctxt->flags -= FLAGS_MIXED_CONTENT; + } state = xmlRelaxNGNewValidState(ctxt, node); if (state == NULL) { ret = -1; @@ -7990,7 +8031,6 @@ xmlRelaxNGValidateState(xmlRelaxNGValidCtxtPtr ctxt, if (ctxt->states != NULL) { tmp = -1; - oldflags = ctxt->flags; ctxt->flags |= FLAGS_IGNORABLE; for (i = 0;i < ctxt->states->nbState;i++) { @@ -8012,6 +8052,7 @@ xmlRelaxNGValidateState(xmlRelaxNGValidCtxtPtr ctxt, ret = xmlRelaxNGValidateElementEnd(ctxt); xmlRelaxNGFreeValidState(ctxt,state); } + ctxt->flags = oldflags; ctxt->state = oldstate; if (oldstate != NULL) oldstate->seq = xmlRelaxNGSkipIgnored(ctxt, node->next); @@ -8695,14 +8736,12 @@ xmlRelaxNGFreeValidCtxt(xmlRelaxNGValidCtxtPtr ctxt) { } xmlRelaxNGFreeStates(NULL, ctxt->freeState); } -#ifdef FS if (ctxt->freeStates != NULL) { for (k = 0;k < ctxt->freeStatesNr;k++) { xmlRelaxNGFreeStates(NULL, ctxt->freeStates[k]); } xmlFree(ctxt->freeStates); } -#endif if (ctxt->errTab != NULL) xmlFree(ctxt->errTab); xmlFree(ctxt); diff --git a/result/relaxng/docbook_0 b/result/relaxng/docbook_0 new file mode 100644 index 00000000..98d19714 --- /dev/null +++ b/result/relaxng/docbook_0 @@ -0,0 +1 @@ +./test/relaxng/docbook_0.xml validates diff --git a/result/relaxng/docbook_0.err b/result/relaxng/docbook_0.err new file mode 100644 index 00000000..a934decd --- /dev/null +++ b/result/relaxng/docbook_0.err @@ -0,0 +1,4 @@ +./test/relaxng/docbook_0.xml:1864: error: Entity 'copy' not defined + &copy; — copyright sign (©) + ^ +Unimplemented block at xmlschemastypes.c:1636 diff --git a/result/relaxng/docbook_err b/result/relaxng/docbook_err new file mode 100644 index 00000000..e69de29b diff --git a/result/relaxng/docbook_valid b/result/relaxng/docbook_valid new file mode 100644 index 00000000..81240128 --- /dev/null +++ b/result/relaxng/docbook_valid @@ -0,0 +1 @@ +./test/relaxng/docbook.rng validates diff --git a/result/relaxng/spec_0 b/result/relaxng/spec_0 new file mode 100644 index 00000000..df30e8a7 --- /dev/null +++ b/result/relaxng/spec_0 @@ -0,0 +1 @@ +./test/relaxng/spec_0.xml validates diff --git a/result/relaxng/spec_0.err b/result/relaxng/spec_0.err new file mode 100644 index 00000000..e69de29b diff --git a/result/relaxng/spec_err b/result/relaxng/spec_err new file mode 100644 index 00000000..e69de29b diff --git a/result/relaxng/spec_valid b/result/relaxng/spec_valid new file mode 100644 index 00000000..27336e13 --- /dev/null +++ b/result/relaxng/spec_valid @@ -0,0 +1 @@ +./test/relaxng/spec.rng validates diff --git a/result/relaxng/tutor8_1_2 b/result/relaxng/tutor8_1_2 new file mode 100644 index 00000000..11c16119 --- /dev/null +++ b/result/relaxng/tutor8_1_2 @@ -0,0 +1 @@ +./test/relaxng/tutor8_1_2.xml validates diff --git a/result/relaxng/tutor8_1_2.err b/result/relaxng/tutor8_1_2.err new file mode 100644 index 00000000..e69de29b diff --git a/test/relaxng/docbook.rng b/test/relaxng/docbook.rng new file mode 100644 index 00000000..85a6aed4 --- /dev/null +++ b/test/relaxng/docbook.rng @@ -0,0 +1,9141 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + changed + added + deleted + off + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BMP + CGM-CHAR + CGM-BINARY + CGM-CLEAR + DITROFF + DVI + EPS + EQN + FAX + GIF + GIF87a + GIF89a + JPG + JPEG + IGES + PCX + PIC + PNG + PS + SGML + TBL + TEX + TIFF + WMF + WPG + linespecific + + + + + + + + + + + + + + + + + + + + + + left + right + center + + + + + + + + + + + + 0 + 1 + + + + + + + + + click + double-click + press + seq + simul + other + + + + + + + + + + + + + + + + + + + + linespecific + + + + + + numbered + unnumbered + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + refentry + none + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + qanda + number + none + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + optional + required + + + + + + + + + + + + + + + + + + + + + + optional + required + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + other + sect1 + sect2 + sect3 + sect4 + sect5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + normal + compact + + + + + + + + + + + + + + + + + + + + + + + + + arabic + upperalpha + loweralpha + upperroman + lowerroman + + + + + + + inherit + ignore + + + + + + + continues + restarts + + + + + + + normal + compact + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + inline + vert + horiz + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + calspair + linecolumn + linerange + linecolumnpair + other + + + + + + + + + + + + + + + + + + + + + + + + + + calspair + linecolumn + linerange + linecolumnpair + other + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + calspair + linecolumn + linerange + linecolumnpair + other + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + monospaced + normal + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BMP + CGM-CHAR + CGM-BINARY + CGM-CLEAR + DITROFF + DVI + EPS + EQN + FAX + GIF + GIF87a + GIF89a + JPG + JPEG + IGES + PCX + PIC + PNG + PS + SGML + TBL + TEX + TIFF + WMF + WPG + linespecific + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + left + right + center + + + + + + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + left + right + center + + + + + + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + opt + req + plain + + + + + + + norepeat + repeat + + + + + + + + + + + + + + + + + + + + + + + + + + + + + opt + req + plain + + + + + + + norepeat + repeat + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + class + interface + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + opt + req + plain + + + + + + + norepeat + repeat + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BMP + CGM-CHAR + CGM-BINARY + CGM-CLEAR + DITROFF + DVI + EPS + EQN + FAX + GIF + GIF87a + GIF89a + JPG + JPEG + IGES + PCX + PIC + PNG + PS + SGML + TBL + TEX + TIFF + WMF + WPG + linespecific + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + service + trade + registered + copyright + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + hardware + software + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + name + table + field + key1 + key2 + record + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + headerfile + devicefile + libraryfile + directory + symlink + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + limit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + cartridge + cdrom + disk + tape + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + command + function + option + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + command + function + option + parameter + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + attribute + attvalue + element + endtag + emptytag + genentity + numcharref + paramentity + pi + xmlpi + starttag + sgmlcomment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + limit + + + + + + + + + + + + + + + + + + + + + + + + + + + constant + groupname + library + macro + osname + resource + systemname + username + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + article + book + chapter + part + refentry + section + journal + series + set + manuscript + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + service + trade + registered + copyright + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + all + global + local + + + + + + + preferred + normal + + + + + + + singular + startofrange + endofrange + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sect2 + sect3 + sect4 + sect5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sect1 + sect3 + sect4 + sect5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sect1 + sect2 + sect4 + sect5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sect1 + sect2 + sect3 + sect5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sect1 + sect2 + sect3 + sect4 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + journalarticle + productsheet + whitepaper + techreport + specification + faq + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + top + bottom + topbot + all + sides + none + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + + top + bottom + topbot + all + sides + none + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + left + right + center + justify + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + left + right + center + justify + char + + + + + + + + + + + + + + + + + + + + + + + + + + + + top + middle + bottom + + + + + + + + + + + + + + + + + + top + middle + bottom + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + top + middle + bottom + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + 1 + + + + + + + 0 + 1 + + + + + + + left + right + center + justify + char + + + + + + + + + + + + + + + + + top + middle + bottom + + + + + diff --git a/test/relaxng/docbook_0.xml b/test/relaxng/docbook_0.xml new file mode 100644 index 00000000..6fe62531 --- /dev/null +++ b/test/relaxng/docbook_0.xml @@ -0,0 +1,4448 @@ + + + + + + + + + + + +]> + + + +
+ + + + + + David + Mason + + Red Hat, Inc. +
+ dcm@redhat.com +
+ + + + + Daniel + Mueth + +
+ d-mueth@uchicago.edu +
+ + + + + Alexander + Kirillov + +
+ kirillov@math.sunysb.edu +
+ + + + + + + This is a pre-release! + + + + + + 0.99 + + + 04.10.2000 + + + + + + 2000 + Red Hat, Inc., Daniel Mueth, and Alexander Kirillov + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.1 or any later version published + by the Free Software Foundation with no Invariant Sections, no + Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy + of the GNU Free Documentation License from + the Free Software Foundation by visiting their Web site or by writing to: + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + + + Many of the names used by companies to distinguish their products and + services are claimed as trademarks. Where those names appear in any + GNOME documentation, and those trademarks are made aware to the members + of the GNOME Documentation Project, the names have been printed in caps + or initial caps. + + + + The GNOME Handbook of Writing Software Documentation + + + + + + + Introduction + + + + + The GNOME Documentation Project + + + Goals + + The GNOME Documentation Project (GDP) aims to provide GNOME + and GNOME applications with a complete, intuitive, and clear + documentation system. At the center of the GDP is the + GNOME Help Browser, which + presents a unified interface to GNOME-specific documentation + as well as other Linux documentation such as man pages and + texinfo documents. The GNOME Help System provides a + comprehensive view of documentation on a machine by + dynamically assembling the documentation of GNOME + applications and components which are installed. The GDP is + responsible for writing numerous GNOME-related documents, + both for developers and for users. Developer documentation + includes APIs for the GNOME libraries, GNOME White + Papers, GNOME developer tutorials, the GNOME Developer + FAQ, the GNOME + Developer's Website, and GNOME + Handbook's, such as the one you are reading. + User documentation include the GNOME User's + Guide, the GNOME FAQ, and + GNOME application documentation. Most GNOME applications + have their own manual in addition to context sensitive help. + + + + + Joining the GDP + + Documenting GNOME and all the numerous GNOME applications is + a very large project. The GDP is always looking for people + to help write, update, and edit documentation. If you are + interested in joining the GDP team, you should join the + + gnome-doc-list mailing list . + Read , for help selecting a + project to work on. Feel free to introduce yourself on the + gnome-doc-list mailing list and indicate which project you + intend to work on, or else ask for suggestions of important + documents which need work done. You may also want to join the + #docs IRC channel on irc.gnome.org to meet other GDP members + and discuss any questions you may have. For a list of GDP + projects and members, see the + + GDP Website. + + + + + Collaborating with the GDP + + GNOME developers, packagers, and translators may not be + writing GNOME documentation but will want to understand how + the GNOME documentation system works and will need to + collaborate with GDP members. This document should help to + outline the structure of how the GNOME documentation system + works. Developers who do not write the documentation for + their applications are encouraged to find a GDP member to + write the documentation. This is best done by sending an + email to the + gnome-doc-list mailing list + describing the application, where it can be downloaded from, + and that the developer(s) would like a GDP member to write + documentation for the application. The #docs IRC channel on + irc.gnome.org is another option for contacting GDP members. + + + + + + + + Notation and Conventions + + This Handbook uses the following notation: + + + + + + /usr/bin + + + Directory + + + + + foo.sgml + + + Filename + + + + + command + + + Command or text that would be typed. + + + + + replaceable + + + "Variable" text that can be replaced. + + + + + Program or Doc Code + + Program or document code + + + + + + + + + + + About This Handbook + + This Handbook is a guide for both writing documentation for + GNOME components and applications and for properly binding and + packaging documentation into GNOME applications. + + + This Handbook, like all GNOME documentation, was written in + DocBook(SGML) and is available in several formats including + SGML, HTML, PostScript, and PDF. For the latest version, see + + Getting The GNOME Handbook of Writing Software + Documentation . Alternately, one may + download it anonymously from GNOME CVS under gnome-docu/gdp. + + + + + + + + Getting Started Writing GNOME Documentation + + + + + Selecting A Document + + + Document Something You Know + + The most frequently asked question of new contributors who + join the GDP is "which document should I start + with?". Because most people involved are volunteers, we do + not assign projects and applications to + write documents for. The first step is all yours - you must + decide what about GNOME interests you most and find out if + it has complete documents or not. + + + It is also important to spend some time with GNOME to make + sure you are familiar enough with it to be + authoritative in your writing. The + best way to do this is to just sit down and play with GNOME + as much as possible before starting to write. + + + The easiest way to get started is to improve existing + documentation. If you notice some inaccuracies or omissions + in the documentation, or you think that you can explain the + material more clearly, just send your suggestions to the + author of the original documentation or to the GNOME + documentation project at docs@gnome.org. + + + + + The GNOME Documentation Status Table + + The GDP Documentation Status Table + (DocTable) (http://www.gnome.org/gdp/doctable/) is a + web page which tracks the status of all the various + documentation components of GNOME. These components include + application documentation, internal GNOME component + documentation, user documentation, and developer + documentation. For each documentation item, it tracks the + current status of the documentation, who is working on the + particular document, where the documentation can be found, + and provides a forum for the discussion of each item. + + + You should use the DocTable to help + you select a documentation item which needs work done. Once + you have selected an item to work on, please register + yourself as an author so that other authors do not duplicate + your work and may contact you to help or offer suggestions. + Also be sure to keep the status icons up-to-date so that + the GDP team can easily identify which items need additional + help. The DocTable also allows + people to make announcements and suggestions and to discuss + issues in the comments section. + + + Note + + Note that the information in the + DocTable may not always be up-to-date + or accurate. When you assign yourself to documenting an + application, make sure you find out the latest status of + documentation by contacting the application author. + + + + + + + + + Installing and Using DocBook + + All documentation for the GNOME project is written in SGML + using the DocBook DTD. There are many advantages to using + this for documentation, not least of which is the single + source nature of SGML. To contribute to the GDP you should + learn to use DocBook. + + + NOTE + + To get started writing for the GDP you do not need to rush + out and learn DocBook - if you feel it is too much to handle + for now, you can submit plain ASCII text to the + gnome-doc-list mailing list + and a volunteer will mark it up for you. Seeing your + document marked up will also be a great way for you to start + learning DocBook. + + + + Installing DocBook + + Download and install the following DocBook Tools packages: jade, docbook, + jadetex, sgml-common, and stylesheets. (RPM users should note + that jade is platform dependent (eg. i386), while the other packages + are in the noarch + directory.) You can find more + information on DocBook Tools here. + + + If you are an Emacs user you may + want to grab the psgml package as well. This is a major mode + for editing sgml files in Emacs. + + + + + GDP Stylesheets + + The GDP uses its own DocBook stylesheets. To use the GDP + stylesheets, you should download the file + gdp-both.dsl from the gnome-docu/gdp/dsssl module in + CVS (or from + GDP Custom DSSSL Stylesheet)and copy it + + over the file + /usr/lib/sgml/stylesheets/cygnus-both.dsl. + Alternately, you can download and install the + gnome-doc-tools package which will set + up the stylesheets as well as the DTD discussed below. + + + + + + + GDP DTD (PNG Image Support) + + Due to some license issues involved with the creation of + gifs, the GNOME Documentation Project has decided to use the + PNG image format for all images in GNOME documentation. You + can read more about the issues involved with gifs at http://www.gnu.org/philosophy/gif.html. + + + The current DocBook DTD(3.1) does not include support for + embedding PNG images in your documents. Since the GDP uses + many screenshots in its documentation, we use our own + variation on the DocBook DTD which has PNG image support. + We encourage everybody to use this DTD instead of the + default DocBook DTD since your source document header and + your output document appearance subtly vary between the two + DTD's. To install the GDP custom DTD with PNG image support + by hand: + + + + + Download the + GDP DocBook DTD for PNG support and install it + where you keep your DTD's. (On Red Hat use /usr/lib/sgml/.) Note that + the 3.0 DTD is missing support for the + <legalnotice> tag, so it is + recommended that you use version 3.1 + + + + + Add the new DTD to your SGML CATALOG file. The location + of your SGML CATALOG file may vary depending upon your + distribution. (On Red Hat it is usually in + /usr/lib/sgml/CATALOG.) Add the following line to this + file: + +PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd" + + If you are using the 3.1 DTD, use: + +PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd" + + + + + + Alternately, you can download and install the + gnome-doc-tools package which will set + up the custom stylesheets and DTD for you. + + + To include PNG files in your documents, you will need to + indicate that you are using this special DTD. To do + this, use the following headers: + + + Articles: + +]]> + + + + Books: + +]]> + + + + + + + Editors + + There are many editors on Linux and UNIX systems available + to you. Which editor you use to work on the sgml documents + is completely up to you, as long as the editor is able to + preserve sgml and produce the source in a format that is + readable by everyone. + + + Probably the two most popular editors available are + Emacs and + vi. These and other editors are + used regularly by members of the GDP. Emacs has a major + mode, psgml, for editing sgml files which can save you time + and effort in adding and closing tags. You will find the + psgml package in DocBook Tools, which is the standard set of + tools for the GDP. You may find out more about DocBook Tools + in . + + + + + Creating Something Useful with your Docs + + The tools available in DocBook Tools allow you to convert + your sgml document to many different formats including html + and Postscript. The primary tool used to do the conversion + is an application called Jade. In + most cases you will not have to work directly with + Jade; Instead, you will use the + scripts provided by DocBook Tools. + + + To preview your DocBook document, it is easiest to convert + it to html. If you have installed the + DocBook tools described above, all you have to do is to run + the command $db2html + mydocument.sgml. If there are no sgml syntax + errors, this will create a directory mydocument and place the + resulting html files in it. The title page of the document + will typically be + mydocument/index.html. If you have + screenshots in your document, you will have to copy these + files into the mydocument directory by + hand. You can use any web browser to view your document. + Note that every time you run db2html, it + creates the mydocument directory over, so + you will have to copy the screenshots over each time. + + + You can also convert your document to PostScript by running + the command $db2ps + mydocument.sgml, after which you can print out or + view the resulting .ps file. + + + NOTE + + The html files you get will not look quite the same as the + documentation distributed with GNOME unless you have the + custom stylesheets installed on your machine. DocBook + Tools' default stylesheets will produce a different look + to your docs. You can read more about the GDP stylesheets + in . + + + + + + Images in DocBook Tools + + If your document uses images you will need to take note of a + few things that should take place in order for you to make + use of those images in your output. + + + The DocBook Tools scripts and applications are smart enough + to know that when you are creating html you will be using + PNG files and when you are creating Postscript you will be + using EPS files (you must use EPS with Postscript). + + + Thus, you should never explicitly + include the extension of the image file, since DocBook + Tools will automatically insert it for you. For example: + + + + My Image + + Sample GNOME Display + + + + +]]> + + You will notice in this example that the file + myfile.png was referred to as simply + myfile. Now when you run + db2html to create an html file, it will + automatically look for myfile.png in + the directory. + + + If you want to create PostScript ouput, you will need to create an + EPS version of your image file to be displayed in the + PostScript file. There is a simple script available which + allows you to change a PNG image into an EPS file + easily. You can download this file - img2eps - from http://people.redhat.com/dcm/sgml.html + (look for the img2eps section). Note that this script is + included in the gnome-doc-tools package, so if you are using + this package, you should already have + img2eps on you system. + + + + + Learning DocBook + + There are many resources available to help you learn DocBook. + The following resources on the web are useful for learning + DocBook: + + + + + http://www.docbook.org - Norman + Walsh's DocBook: The Definitive + Guide. Online O'Reilly book on using + DocBook. Contains an excellent element reference. May be + too formal for a beginner. + + + + + A Practical Introduction to DocBook + - The Open Source Writers Group's introduction to using + DocBook. This is an excellent HOW-TO type article on + getting started. + + + + + Getting Going with DocBook: Notes for + Hackers - Mark Galassi's introduction to DocBook + for hackers. This has to be one of the first + introductions to DocBook ever - still as good as it ever + was. + + + + + + FreeBSD Documentation Project Primer for New + Contributors - FreeBSD documentation project + primer. Chapter 4.2 provides a very good introduction to + writing documentation using DocBook. Note that it also + describes some custom extensions of DocBook; + fortunately, they are clearly marked as such. + + + + + Norman Walsh's book is also available in print. + + + The following sections of this document are designed to help + documentation authors write correct and consistent DocBook: + + + + + - Descriptions of + commonly used DocBook tags. + + + + + You may also discuss specific DocBook questions with GDP + members on the #docs IRC channel at irc.gnome.org and on the + gnome-doc-list mailing list. + + + + + + + + + + GDP Document Templates + + Templates for various types of GNOME documents are found in + . They are kept in CVS in + gnome-docu/gdp/templates. The easiest source to get them from + is probably the GDP + Document Templates web page, which is typically kept + completely up-to-date with CVS and has a basic description of + each file from CVS. + + + + + + + Screenshots + + Most GNOME documents will have screenshots of the particular + applet, application, GNOME component, or widget being + discussed. As discussed above in you + will need to install the special GDP DocBook DTD which + supports PNG images, the format used for all images in GNOME + documentation. For the basic DocBook structure used to insert + images in a document, see above. + + + Screenshot Appearance + + For all screenshots of windows that typically have border + decorations (e.g. applications and dialogs, but not applets + in a panel), GDP standards dictate + the appearance of the window. (This is to minimize possible + confusion to the reader, improve the appearance of GNOME + documents, and guarantee the screenshot is readable when + printed.) All screenshots should be taken with the SawFish + (formerly known as Sawmill) window manager using the + MicroGui theme and Helvetica 12pt font. (A different window + manager can be used provided the MicroGui theme is available + for this window manager and the appearance is identical to + that when using the SawFish window manager.) The default + GTK+ theme(gtk) and font (Helvetica 12 pt) should be used + for all screenshots. If you are unable to provide + screenshots in this form, you should create screenshots as + you wish them to appear and send them to the + + gnome-doc-list mailing list + requesting a GDP member reproduce these screenshots in the + correct format and email them to you. + + + + Screenshot Tools + + There are many tools for taking screenshots in + GNOME/Linux. Perhaps the most convenient is the + Screen-Shooter Applet. Just click + on the window icon in the applet and then on the window you + would like to take a screenshot of. (Note that + at the time of this writing, PNG images taken by + screenshooter do not appear properly in + Netscape or the + GNOME Help Browser. You + should save your screenshot as a GIF and + then use convert filename.gif + filename.png.) For applets + in a Panel, + xv can be used to crop the + screenshot to only include the relevant portion of the + Panel. Note that + xv and + gimp can both be used for taking + screenshots, cropping screenshots, and converting image + formats. + + + + Screenshot Files + + Screenshots should be kept in the main documentation + directory with your SGML file for applets, or should be + kept in a directory called "figs" for application and other + documentation. After you use db2html to + convert your SGML file to HTML (see ), you will need to copy your + screenshots (either the individual PNG files for applet + documentation, or the whole "figs" directory for other + documentation) into the newly created HTML directory. Note + that every time you use db2html the HTML + directory is erased and rewritten, so do not store your only + copy of the screenshots in that directory. If you wish to + create PostScript or PDF output, you will need to manually + convert the PNG images to EPS as described in , but will not need to copy these + images from their default location, as they are included + directly into the output(PostScript of PDF) file. + + + + + + + + + Application Bugs + + Documentation authors tend to investigate and test applets and + applications more thoroughly than most + users. Often documentation authors will discover one or + more bugs in the software. These bugs vary from small ones, + such as mis-spelled words or missing + About dialogs in the menu, to large + ones which cause the applet to crash. As all users, you + should be sure to report these bugs so that application + developers know of them and can fix them. The easiest way to + submit a bug report is by using the Bug + Buddy applet which is part of the gnome-applets + package. + + + + + + + + Using CVS + + CVS (Concurrent Versions System) is a tool that allows + multiple developers to concurrently work on a set of + documents, keeping track of the modifications made by each + person. The files are stored on a server and each developer + checks files out, modifies them, and then checks in their + modified version of the files. Many GNOME programs and + documents are stored in CVS. The GNOME CVS server allows + users to anonymously check out CVS files. Most GDP members + will need to use anonymous CVS to download the most up-to-date + version of documentation or programs. Modified documents will + typically be emailed to the the application developer. Core + GDP members may also be granted login CVS privileges so they + may commit modified files directly to CVS. + + + + Anonymous CVS + + To anonymously check out documents from CVS, you must first + log in. From the bash shell, you should set your CVSROOT + shell variable with export + CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome' + and then login with cvs login(there is no + password, just hit return). As an example, we will use the + "gnome-docu/gdp" module which contains this and several + other documents. To check these documents out for the first + time, type cvs -z3 checkout + gnome-docu/gdp. After you have this document + checked out and you would like to download any updates on + the CVS server, use cvs -z3 update -Pd. + + + + + Login CVS If you have been given a + login for the GNOME CVS server, you may commit your file + modifications to CVS. Be sure to read the following section + on CVS etiquette before making any commits to CVS. To log in + to the CVS server as user + username with a + password, you must first set your CVSROOT shell variable with + export + CVSROOT=':pserver:username@cvs.gnome.org:/cvs/gnome'. + Log in with cvs login and enter your + password. You may check out and update modules as described + above for anonymous CVS access. As a login CVS user, you may + also check modified versions of a file into the CVS server. + To check + filename into + the CVS server, type cvs -z3 commit + filename. You will be + given a vi editor window to type in a brief log entry, + summarizing your changes. The default editor can be changed + using the EDITOR environment variable or + with the option. You + may also check in any modifications to files in the working + directory and subdirectories using cvs -z3 + commit. To + add a new file to the CVS server, use cvs -z3 add + filename, followed by the + commit command. + + + + + CVS Etiquette + + Because files in CVS are typically used and modified by + multiple developers and documentation authors, users should + exercise a few simple practices out of courtesy towards the + other CVS users and the project leader. First, you should + not make CVS commits to a package without first discussing + your plans with the project leader. This way, the project + leader knows who is modifying the files and generally, what + sort of changes/development is being done. Also, whenever a + CVS user commits a file to CVS, they should make an entry in + the CVS log and in the ChangeLog so + that other users know who is making modifications and what + is being modified. When modifying files created by others, + you should follow the indentation scheme used by the initial + author. + + + + + + + + + The GNOME Documentation System + + + + + The GNOME Help Browser + + At the core of the GNOME help system is the GNOME + Help Browser. The Help + Browser provides a unified interface to several + distinct documentation systems on Linux/Unix systems: man + pages, texinfo pages, Linux Documentation Project(LDP) + documents, GNOME application documentation, and other GNOME + documents. + + + The GNOME Help Browser works by + searching standard directories for documents which are to be + presented. Thus, the documentation that appears in the GHB is + specific to each computer and will typically only represent + software that is installed on the computer. + + + + + + + The GNOME Help Browser (GNOME-2.0) In + GNOME 2.0, the GNOME Help Browser + will be replaced by Nautilus. + Nautilus will be the file manager/graphical shell for GNOME 2.0 + and will also implement a more sophisticated help system than + that used by the GNOME Help Browser + used in GNOME 1.0. It will read and display DocBook files + directly, avoiding the need for duplicating documents in both + DocBook and HTML formats. Its display engine for DocBook will + be much faster than running jade to + convert to HTML for rendering. Because it uses the original + DocBook source for documentation, it will be possible to do more + sophisticated searching using the meta information included in + the documents. And since Nautilus is a virtual file system + layer which is Internet-capable, it will be able to find and + display documents which are on the web as well as those on the + local file system. For more information on + Nautilus, visit the #nautilus IRC + channel on irc.gnome.org. + + + + + + Dynamic Document Synthesis(GNOME-2.0) + + GNOME uses the documentation presented by all the various + GNOME components and applications installed on the system to + present a complete and customized documentation environment + describing only components which are currently installed on a + users system. Some of this documentation, such as the manuals + for applets, will be combined in such a way that it appears to + be a single document. + + + By using such a system, you can be sure that any GNOME app you + install that has documentation will show up in the index, + table of contents, any search you do in the help browser. + + + + + + + The GNOME Documentation Components + + + Application Manuals + + Every GNOME application should have an application manual. + An application manual is a document specific to the + particular application which explains the various windows + and features of the application. Application Manuals + typically use screenshots (PNG format) for clarity. Writing + application manuals is discussed in more detail in below. + + + + + Application Help + + Applications should have a Help + button on screens on which users may need help. These + Help buttons should pull up the + default help browser, determined by the + ghelp URL Handler (configured using the + Control Center), typically the + GNOME Help Browser. The help + browser should show either the first page of the application + manual, or else the relevant page thereof. Application help + is described in more detail in below. + + + + + Application Context Sensitive Help (coming in + GNOME-2.0) + + Context sensitive help is a system which will allow the user + to query any part (button, widget, etc.) of an application + window. This is done by either entering a CS Help mode by + clicking on an icon or by right clicking on the application + part and selecting "What's This" or whatever is decided on + at the time. Context sensitive help is described in more + detail in + below. + + + + + The GNOME User Guide + + The GNOME User Guide describes the + GNOME desktop environment and core components of GNOME such + as the panel and + control center. In GNOME 1.x this + was the main and only source of documentation. In GNOME 2.0 + this will become a document for the web and for printing + that is derived from various parts chosen in the system that + are necessary for the new user to understand. + + + + + User Documents + + Aside from the GNOME User Guide, + there are several other documents to help GNOME users learn + GNOME, including the GNOME FAQ, + GNOME Installation and Configuration + Guide, and the GNOME Administrators + Guide. + + + + + Developer Documents + + There are many White Papers, Tutorials, HOWTO's and FAQ's to + make programming GNOME and GNOME applications as easy as + possible. + + + API documentation is also available for the GNOME libraries. This is + detailed documentation of the code that is used to build GNOME + apps. You can keep up with the GNOME API docs on the GNOME API + Reference page. + + + + + Project Documents + + Some GNOME projects have documentation to maintain + consistency in their product and to help new contributors + get up to speed quickly. Among these are the GDP documents, + such as the one you are reading now. + + + + + + + + + + DocBook Basics + + + + Introduction to DocBook + + To understand DocBook, a basic understanding of SGML is + helpful. SGML stands for Standard General Markup Language and + is one of the first markup languages every created. HTML is + actually derived from SGML and XML is a subset of SGML. SGML + uses what is called a Document Type Definition to specify + elements which are contained between + brackets, < and >. Text is marked by both beginning and + ending elements, for example in the DocBook DTD, one denotes a + title with <title>The + Title</title>. + + + The DTD (in the case of the GDP, DocBook) defines rules for how the + elements can be used. For example, if one element can only be used when + embedded within another, this is defined in the DTD. + + + An SGML file is just a plain ASCII file containing the text + with the markup specified above. To convert it to some easily + readable format, you need special tools. The GDP uses DocBook + Tools, a free package of utilities for working with DocBook + which includes Jade, which does the SGML/DSSL + parsing. You can read more about DocBook Tools in . + + + The final appearance of the output (e.g. PostScript or HTML) + is determined by a + stylesheet. Stylesheets are files, + written in a special language (DSSSL — Document Style + Semantics and Specification Language), which specify the + appearance of various DocBook elements, for example, + what fonts to use for titles and various inline elements, page + numbering style, and much more. DocBook tools come with a + collection of stylesheets (Norman Walsh's modular + stylesheets); GNOME Document Project uses some customized + version of this stylesheets — see . + + + The advantage of specifying the structure + of a document with SGML instead of specifying the + appearance of the document with a typical + word processor, or with html, is that the resulting document + can be processed in a variety of ways using the structural + information. Whereas formatting a document for appearance + assumes a medium (typically written text on a standard-sized + piece of paper), SGML can be processed to produce output for a + large variety of media such as text, postscript, HTML, + Braille, audio, and potentially many other formats. + + + Using 'content' as the elements to define the text of a document also + allows for search engines to make use of the actual elements to make a + "smarter search". For example, if you are searching for all documents + written by the author "Susie" your search engine could be made smart + enough to only search <author> elements, making for a faster and more + accurate search. + + + Since the overall appearance of the output is determined not by the DTD + or the SGML document, but rather by a stylesheet, the appearance of a + document can be easily changed just by changing the stylesheet. This + allows everyone in the project to create documents that all look the + same. + + + As stated before, the GDP uses the DocBook DTD. For a list of + introductory and reference resources on DocBook, see . The following sections also provide + convenient instructions on which markup tags to use in various + circumstances. Be sure to read + for GDP documentation-specific guidelines. + + + + + + XML and SGML + + In not so distant future (probably before GNOME 2.0), + DocBook itself and GNOME Documentation project will migrate from + SGML to XML. This transition should be relatively painless: + (almost) all DocBook tags will remain the same. However, XML has + stricter syntax rules than SGML; thus, some constructions which + are valid in SGML will not be valid in XML. Therefore, to be + ready for this transistion, it is strongly + advised that the documentation writers conform to XML + syntax rules. Here are most important differences: + + + + + Minimization + + + + It is possible with some implementations of SGML to use + minimizations to close elements in a document by using + </>, for example: + <title>The + Title</>. This is not + allowed in XML. You can use sgmlnorm command, + included in DocBook Tools package, to expand minimized tags; + if you are using Emacs with psgml + mode, you can also use menu command + + Modify + Normalize + . + + + + + Self-closing tags + + + + Also, in SGML some tags are allowed not to have closing + tags. For example, it is legal for + <xref> not to have a closing tag: + <xref + linkend="someid">. In + XML, it is illegal; instead, you should use + <xref + linkend="someid"/> (note the + slash!). + + + + + + Case sensitive tags + + + In XML, unlike SGML, tags are case-senstive + <title> and + <TITLE> are different tags! + Therefore, please always use lowercase tags (except for + things like DOCTYPE, CDATA and + ENTITY, which are not DocBook tags). + + + + + + + + + + + + + + + Structure Elements + + + Sections and paragraphs + + Top-level element of a book body must be + <chapter>; it may contain one or more + <sect1>, each of them may contain + <sect2> and so on up to + <sect5>. The top-level element of an + article body is always + <sect1>. Regardless of which elements + you use, give each structural element a unique id, so that + you can link to it. For usage example, see the template. + + Please try to avoid using deeply nested sections; for + most situations, <sect1> and + <sect2> should be sufficient. If not, + you probably should split your <sect1> + into several smaller ones. + + Use the tag <para> for + paragraphs, even if there is only one paragraph in a + section—see template for examples. + + + + + Notes, Warnings, And Tips + + For notes, tips, warnings, and important information, which + should be set apart from the main text (usually as a + paragraph with some warning sign on the margin), use tags + <note>, <tip>, + <warning>, + <important> respectively. For example: + + + TIP + + To speed up program compilation, use gcc + compiler with Pentium optimization. + +]]> produces + + + TIP + + To speed up program compilation, use + gcc compiler with Pentium + optimization. + + + Note that this should not be inside a + <para> but between paragraphs. + + + + Screenshots and other figures + + To include screenshots and other figures, use the following + tags: + + + + Screenshot + + Screenshot of a program + + + +]]> + + replacing example_screenshot with the + actual file name (without extension). The result will look like this: + +
+ Screenshot + + Screenshot of a program + + + +
+ + + NOTE + + Notice in this example that the screenshot file name does + not include the file type extension — to find out + why, please read . + + + + + Program listings and terminal session + To show a file fragment—for example, program + listing—use <programlisting> tag: + + +[Desktop Entry] +Name=Gnumeric spreadsheet +Exec=gnumeric +Icon=gnome-gnumeric.png +Terminal=0 +Type=Application +]]> + + which produces + +[Desktop Entry] +Name=Gnumeric spreadsheet +Exec=gnumeric +Icon=gnome-gnumeric.png +Terminal=0 +Type=Application + + As a matter of fact, all examples in this document were + produced using <programlisting>. + + + To show a record of terminal session—i.e., sequence of + commands entered at the command line—use + <screen> tag: + + +bash$make love +make: *** No rule to make target `love'. Stop. +]]> + + which produces + +bash$make love +make: *** No rule to make target `love'. Stop. + + Note the use of tags <prompt> and + <userinput> for marking system prompt + and commands entered by user. + + NOTE + + Note that both <programlisting> + and <screen> preserve linebreaks, + but interpret SGML tags (unlike LaTeX + verbatim environment). Take a look at + the source of this document to see how you can have SGML + tags literally shown but not interpreted, + + + + + + Lists + + The most common list types in DocBook are + <itemizedlist>, + <orderedlist>, and + <variablelist>. + + + + <itemizedlist> + + This is the simplest unnumbered list, parallel to + <ul> in HTML. Here is an example: + + + + + Show backup files — This will + show any backup file that might be on your system. + + + + + Show hidden files — This will + show all "dot files" or files that begin with a dot. This + files typically include configuration files and directories. + + + + + Mix files and directories — This + option will display files and directories in the order you + sort them instead of + always having directories shown above files. + + + +]]> + + and output: + + + + + Show backup files — + This will show any backup file that might be on + your system. + + + + + + Show hidden files — + This will show all "dot files" or files that + begin with a dot. This files typically include + configuration files and directories. + + + + + + Mix files and directories + — This option will display files and + directories in the order you sort them instead + of always having directories shown above files. + + + + Note the use of &mdash; + for long dash (see ). Also, + please note that the result looks much nicer because the + terms being explained (Show backup + files, etc.) are set in a different font. In + this case, it was achieved by using <guilabel> + tag. In other cases, use appropriate tags such as + <guimenuitem>, + <command>, + or — if none of + this applies — use + <emphasis>. + + + + + <orderedlist> + + This list is completely analogous to + <itemizedlist> and has the same + syntax, but it produces numbered list. By default, + this list uses Arabic numerals for numbering entries; + you can override this using numeration, + for example <orderedlist + numeration="lowerroman">. Possible values of + these attribute are arabic, + upperalpha, + loweralpha, + upperroman, + lowerroman. + + + + + <variablelist> + This list is used when each entry is + rather long, so it should be formatted as a block of text + with some subtitle, like a small subsection. The + <variablelist> is more complicated + than itemizedlists, but for larger blocks of text, or when + you're explaining or defining something, it's best to use + them. Their greatest advantage is that it's easier for a + computer to search. The lines you are reading now were + produced by <variablelist>. The + source looked liked this: + + + + <itemizedlist> + + This is the simplest unnumbered list, parallel to + <ul> in HTML. Here is an example:... + + + + <orderedlist> + + This list is completely analogous to + <itemizedlist> + + + + <variablelist> + + This list is used when each entry is rather long,... + + + +]]> + + + + + + + Lists can be nested; in this case, the stylesheets + are smart enough to change the numeration (for + <orderedlist>) or marks of each entry + (in <itemizedlist>) for sub-lists + + + + + + + + + Inline Elements + + + GUI elements + + + + <guibutton> — used for + buttons, including checkbuttons and radio buttons + + + + + + <guimenu>, + <guisubmenu> —used for + top-level menus and submenus + respectively, for example Utilities submenu of the + Main Menu]]> + + + + + + <guimenuitem>—an entry in a + menu + + + + + + <guiicon>—an icon + + + + + + <guilabel>—for items which have + labels, like tabs, or bounding boxes. + + + + + <interface>— for most everything + else... a window, a dialog box, the Panel, etc. + + + + + If you need to refer to a sequence of menu choices, such as + + Main Menu + Utilities GNOME + terminal + + there is a special construction for this, too: + + + Main Menu Utilities + GNOME terminal ]]> + + + + + + Links and references + + To refer to another place in the same document, you can use + tags <xref> and + <link>. The first of them + automatically inserts the full name of the element you refer + to (section, figure, etc.), while the second just creates a + link (in HTML output). Here is an example: + +tip was given in +. ]]> + + which produces: An example of a tip was given in . + + + Here notes and extip + are the id attributes of and of the + example of a tip in it. + + To produce a link to an external source, such as a + Web page or a local file, use <ulink> + tag, for example: + +GNOME Web page ]]> + + which produces: To find more about GNOME, please visit + The GNOME Web + Site You can use any of the standard URL types, such + as http, ftp, file, telnet, mailto (in + most cases, however, use of mailto is + unnecessary—see discussion of + <email> tag). + + + + Filenames, commands, and other + computer-related things + + Here are some tags used to describe operating system-related + things: + + + + <filename> — used + for filenames, + e.g.<filename> + foo.sgml + </filename> + produces: foo.sgml. + + + + <filename + class="directory"> — used for + directories, e.g.<filename + class="directory">/usr/bin + </filename> + produces: /usr/bin. + + + + + <application> — used for + application names, + e.g. <application>Gnumeric + </application> produces: + Gnumeric. + + + + + <envar> — used for + environment variables, e.g. + <envar>PATH</envar>. + + + + + + <command> — used for + commands entered on command line, e.g. + <command>make install + </command> produces: + make install. + + + + + <replaceable> — used for + replaceable text, e.g. + <command>db2html<replaceable> + foo.sgml + </replaceable></command> + produces: db2html + foo.sgml. + + + + + + + Keyboard input + To mark up text input by the user, use + <userinput>. + + To mark keystrokes such as shortcuts and other + commands, use <keycap>. + This is used for marking up what is printed on the top + of the physical key on the keyboard. There are a couple of + other tags for keys, too: <keysym> + and <keycode>. However you are + unlikely to need these for most documentation. For reference, + <keysym> is for the symbolic + name of a key. <keycode> is + for the scan code of a key. These are not + terms commonly required in GNOME documentation, + although <keysym> is useful for marking + up control codes. + + + To mark up a combination of keystrokes, use the + <keycombo> wrapper: + + + Ctrl + Alt + F1 +]]> + + + + Finally, if you want to show a shortcut for some menu + command, here are the appropriate tags (rather long): + + + + Ctrlq + + Quit +]]> + + which produces simply + + Ctrl-q + Quit + + + + + + E-mail addresses To mark up e-mail + address, use <email>: + +me@mydomain.com)]]> + + which produces: The easiest way to get in touch with me is + by e-mail (me@mydomain.com) Note that + <email> automatically produces a link + in html version. + + + + + Special symbols + + DocBook also provides special means for entering + typographic symbols which can not be entered directly + form the keyboard (such as copyright sign). This is done using + entities, which is SGML analogue of + macros, or commands, of LaTeX. They generally have the form + &entityname;. Note that the semicolon + is required. + + + here is partial list of most commonly used enitites: + + + + &amp; — ampersend (&) + + + &lt; — left angle bracket (<) + + + &copy; — copyright sign (©) + + + &mdash; — long dash (—) + + + &hellip; — ellipsis (…) + + + + Note that the actual look of the resulting symbols depends + on the fonts used by your browser; for example, it might + happen that long dash (&mdash;) looks + exactly like the usual dash (-). However, in the PostScript + (and thus, in print) the output will look markedly better if + you use appropriate tags. + + + + + + + + + GDP Documentation Conventions + + + + + Conventions for All GDP Documentation + + XML compatibility + + All GNOME documentation should conform to XML syntax + requirements, which are stricter than SGML ones — see + for more informaion. + + + + + Authors' names + + All GNOME documentation should contain the names of both the + application authors and documentation authors, as well as a + link to the application web page (if it exists) and + information for bug submission — see templates for an + example. + + + + + + + + Conventions for Application Documentation + + + Application Version Identification + + Application documentation should identify the version of the + application for which the documentation is written: + + + Introduction + + blah-blah-blah This document describes version 1.0.53 of gfoo. + +]]> + + + + + Copyright information + Application + documentation should contain a copyright notice, stating the + licensing terms. It is suggested that you use the GNU Free + Documentation License. You could also use some other license + allowing free redistribution, such as GPL or Open Content + license. If documentation uses some trademarks (such as UNIX, + Linux, Windows, etc.), proper legal junk should also be + included (see templates). + + + + Software license + + All GNOME applications must contain information about the + license (for software, not for documentation), either in the + "About" box or in the manual. + + + + + Bug reporting + + Application documentation should give an address for + reporting bugs and for submitting comments about the + documentaion (see templates for an example). + + + + + + + + + Writing Application and Applet Manuals + + Every GNOME application or applet should have a manual specific + to that particular application. This manual should be a complete + and authoritative guide. The manual should describe what the + program does and how to use it. Manuals will typically describe + each window or panel presented to the user using screenshots (in + PNG format only) when appropriate. They should also describe + each feature and preference option available. + + + Documentation Availability + + Applications and applets should not rely on documentation + which is only available on the internet. All manuals and + other documentation should be packaged with the application or + applet and be made available to the user through the standard + GNOME help system methods described below. + + + Application manuals should be based on the template in + . Applet manuals should be based on + the templates in for GNOME + versions 1.x and the templates in + for GNOME versions 2.x. + + + Manuals For Large Applications + + Manuals for very large applications, such as GNOME Workshop + components should be a <book> (and thus + use <chapter> for each primary section) + , instead of <article> which most + applications use(with each primary section being a + <sect1>). + + + + Applet Manuals in GNOME 2.0 + + Note that applet manuals in GNOME 2.0 are treated in a special + way. The manuals for all applets are merged into a single + virtual document by Nautilus. For this reason, the header + information for applet manuals is omitted and the first + section of each applet is + <sect1>. Applet manuals will typically + have several sections, each of which is + <sect2>. + + + + Application manuals should be made available by having a + "Manual" entry in the Help pull-down menu + at the top of the + application, as described in . + Applets should make their manuals available by + right-clicking on the applet. + + + + + + + + Listing Documents in the Help Menu + + + Developer Information + + This section is for developers. Documentation authors + generally do not need to know this material. + + + + Typically the application manual and possibly additional help + documents will be made available to the user under the + Help menu at the top right of the + application. To do this, you must first write a + topic.dat file. The format for this file is: + +One line for each 'topic'. + +Two columns, as defined by perl -e 'split(/\s+/,$aline,2)' + +First column is the HTML file (and optional section) for the topic, +relative to the app's help file dir. + +Second column is the user-visible topic name. + + For example, Gnumeric's + topic.dat file is: + +gnumeric.html Gnumeric manual +function-reference.html Gnumeric function reference + + When the application is installed, the + topic.dat file should be placed in the + $prefix/share/gnome/help/appname/C/ directory + where appname is replaced by the + application's name. The application documentation (converted + from SGML into HTML with db2html) should be + placed in this directory too. + + + + If the help files are not present in the correct directory, the + menu items will NOT appear when the program is run. + + + + The topic.dat file is used by the GNOME + menu building code to generate the Help + menu. When you define your menu: + +GnomeUIInfo helpmenu[] = { + {GNOME_APP_UI_ITEM, + N_("About"), N_("Info about this program"), + about_cb, NULL, NULL, + GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT, + 0, 0, NULL}, + GNOMEUIINFO_SEPARATOR, + GNOMEUIINFO_HELP("appname"), + GNOMEUIINFO_END + }; + + the line specifying GNOMEUIINFO_HELP causes + GNOME to create a menu entry which is tied to the documentation + in the directory mentioned above. Also, all the topics in the + topic.dat file will get menu entries in the + Help menu. When the user selects any of these + topics from the Help menu, a help browser + will be started with the associated HTML documentation. + + + + + + + + Application Help Buttons + + + Developer Information + + This section is for developers. Documentation authors + generally do not need to know this material. + + + + Most GNOME applications will have Help + buttons. These are most often seen in Preference windows. (All + Preference windows should have Help + buttons.) Most Help buttons will connect + to the application manual, although some may connect to special + documents. Because the Help buttons do + not generally have their own special documentation, the + documentation author(s) do not need to do very much. However, + the application author must be careful to guarantee that the + application correctly opens the help documentation when the + Help buttons are pressed. + + + To make the Help buttons call the correct document in the GNOME Help + Browser the developer should add code based on the following example: + + +gchar *tmp; +tmp = gnome_help_file_find_file ("module", "page.html"); +if (tmp) { + gnome_help_goto(0, tmp); + g_free(tmp); +} + + + NOTE + + The example above is in the C language, please refer to other + documentation or forums for other GNOME language bindings. + + + + + + + + Packaging Applet Documentation + + Applet Documentation Files + + In GNOME 2.0 each applet will have its own documentation + installed separately, and the GNOME 2.0 help + browser (Nautilus) will dynamically + merge the applet documents into a single virtual book + called GNOME Applets. During the + transitionary stage between GNOME 1.0 and GNOME 2.0, each + applet in the gnome-applets package has its own manual(stored + with the applet in CVS), but they are merged together manually + to create the GNOME Applets book before + distribution. Telsa + hobbit@aloss.ukuu.org.uk is the maintainer of + this document. Applet documentation should be sent to Telsa + (or placed in CVS) who will make sure they are correctly + packaged with the applets. The applet author should be + contacted to modify the menu items and help buttons to bind to + the applet documentation if necessary. + + + Images which are part of the applet documentation should be in + PNG format and should reside in the same directory as the SGML + document file in CVS(gnome-applets/APPLETNAME/help/C). + + + Applets which are not part of the gnome-applets package must + package their documentation with the particular applet + package. They should use the same applet template as other + applets. However, the <xref> links to + the introductory chapter of the GNOME + Applets book must be removed (as the 1.x + GNOME Help Browser does not allow + you to create links between separate documents) and replaced + with suitable text. Note that since this document is not part + of the GNOME Applets book, you must + remember to add <legalnotice> and + <copyright> sections. + + + + + Adding Documentation to an Applet Menu + + Developer Information + + This section is for developers. Documentation authors + generally do not need to know this material. + + + + Applets should have About and + Manual menu items, typically as the first + and second top-most items in the menu respectively. This + section describes how the developer creates these menu items + and links them to the documentation. + + + To add an applet's manual to its applet menu, use: + +/* add an item to the applet menu */ +applet_widget_register_callback(APPLET_WIDGET(applet), "manual", +_("Manual"), &open_manual, NULL); + + Here the second argument is an arbitrary name for the + callback, the third argument is the label which will appear + when the user right clicks on the applet, and the fourth + argument is the callback function. + + + You will need to write a simple callback function to open the + help browser to the appropriate document. This is done using + the gnome_help_file_find_file function, + as described in . + + + You will also want to add an About menu + item to the applet's menu. This is a + stock menu item and is done: + +applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about", + GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about, + NULL); + + + + More information can be found at Writing + GNOME panel applets using the GTK+/GTK-- widget set. + + + + + + + + + Writing Context Sensitive Help (coming in GNOME-2.0) + + Context sensitive help, also known as "pop-up" help, will allow + a user to obtain help information about specific buttons or + parts of an application. + + + Context sensitive help is still under development and not all + the details are available at this time. However, the basics can + be shown here so that you can understand how the system will + work. + + + The Context Sensitive Help system is designed to allow the + developer to give an id to a particular portion of the User + Interface, for example, a button. Once the interface is complete + a Perl script can then be run against the interface code to + create a "map" file. This map file allows the developer or + writer to associate particular paragraph sections from an XML + document to the interface items. + + + The XML used for the document is a small XML DTD that is being + developed to use the same tags (albeit, much fewer) as DocBook + so that writers do not have to re-learn a new DTD. + + + Once the document is written and map file is complete, when the + user launches context sensitive help on the interface (either by + pressing a button and then clicking on the interface item they + want information on, or by right mouse clicking on the interface + item and selecting a pop-up menu item like "What's This") a + small transient window will appear with brief but detailed + information on the interface item. + + + + + + + Referring to Other GNOME Documentation (coming in + GNOME-2.0) + + In the GNOME 2.0 Help System, you will be able to create links + from one document to another. The exact mechanism for doing + this is in development. + + + + + + + + Basics of Documentation Style + + Most people have never enjoyed reading a software manual, and + they probably never will. Many times, they'll read the + documentation only when they run into problems, and they'll be + frustrated and upset before they even read a word. On the + other hand, some readers will read the manual all the way + through, or at least look at the introduction before they + start. Your document might serve as a reference for an expert + or a guide to a beginner, and it must have enough depth to + satisfy the first without overwhelming the second. Ideally, it + will serve beginners as they become + experts. Remember, your goal is to produce complete, + intuitive and clear documentation. + + + In order to write useful documentation, you'll have to know who + your audience is likely to be. Then, you can look for the + problems they're likely to run into, and solve them. It will + also help if you focus on the tasks users will perform, and + group features accordingly, rather than simply describing + features at random. + + + + + + Planning + + Begin documenting by learning how to use the application and + reading over any existing documentation. Pay attention to + places where your document will differ from the template. It + may help to develop a document skeleton: a valid XML or SGML + document that has little or no content. For very large + applications, you will need to make significant departures + from the templates, since you'll be using the + <book> tag instead of + <chapter> or + <article>. + + + + + + + Achieving a Balanced Style + + + Just as you need to juggle expert and novice readers, + you'll have to juggle a number of other extremes as you write: + + + + Documents should be complete, yet concise. You should + describe every feature, but you'll have decide how much + detail is really necessary. It's not, for example, + necessary to describe every button and form field in a + dialog box, but you should make sure that your readers + know how to bring up the dialog and what it does. If + you spend fewer words on the obvious, you can spend more + time clarifying the ambiguous labels and explaining + items that are more complex. + + + + + Be engaging and friendly, yet professional. Games + documents may be less formal than productivity + application documents (people don't + use games, they + play them), but all of them should + maintain a standard of style which holds the reader's + interest without resorting to jokes and untranslatable + allusions or puns. + + + + + + Examples, tips, notes, and screenshots are useful to + break up long stretches of text, but too many can get in + the way, and make your documents too choppy to read. + It's good to provide a screenshot of any dialog windows + a user might run into, but if a dialog box has several + tabs, it's not usually necessary to have one for each. + + + + + + The GDP strives to have all of its documentation conform + to certain standards of style and content, but every + document (and every writer) is different. You will need + to use your judgement, and write documents to fit with + the rest of the project, without compromising the + individual needs of your subject, or your own + individuality as a writer. + + + + + + + + + + + + Structure + + In general, you won't have to worry too much about structure, + because the templates provide you with an excellent example. + As a general rule, try to follow that structural example. + That means using links, hierarchical nesting, and, if + necessary, a glossary or index. You probably won't need to + use every available structural tag, but take advantage of + what DocBook provides you. + + + As to linking, there's some disagreement about whether to use + <xref> <link> + when you make links within your documents. You'll have to + decide, based on the different ways that they are presented + in output, which is more appropriate given the context. + Regardless of which you use, you should not forget to use + them. Help your readers find information that relevant to + the issue at hand. + + + The table of contents will be generated automatically, but + you will probably have to develop your own index if you wish + to have one. The Nautilus Help Browser will have new, and + currently unknown, indexing capabilities, so index style and + structure are still under discussion. The GNOME User's Guide + will contain a glossary in its next versions; unless you're + writing a<book>, it will probably be best to + contribute to that rather than developing your own. + + + + + + Grammar and Spelling + + Nobody expects you to be perfect; they just expect the + documentation for their software to be error-free. That means + that, in the same way that developers look for bugs and accept + bug reports, writers must check for errors in their documents. + Poor grammar, bad spelling, and gross technical errors in + draft documents are fine. However, if those problems show up + in a "real" release, they can count against the credibility of + GNOME and Linux. They'll also make you look bad. + + + There is no substitute for a human proofreader; use a + spell-check program, then read it over yourself, and then find + someone else to help you. Other GDP members are, of course, + willing and able to help you, but non-writers are often at + least as helpful. + + + Proofreading documents is both a also a good way to + familiarize yourself with documentation, and it certainly + makes you valuable to the GDP. Help other writers proof their + documents, and they will help you with yours. + + + + + + + + Teamwork + + + Working With The GDP Team + + The GDP team is a valuable resource for any documentation + author. GDP members can answer most questions documentation + authors have during the course of their work. It is also + important to make sure you are not duplicating work of other + GDP members by visiting the GDP Documentation + Status Table (http://www.gnome.org/gdp/doctable/) and + assigning a documentation item to yourself. This table also + provides a forum for making suggestions and announcements for + each documentation item. The best way to get in touch with + GDP members is on the #docs IRC channel at irc.gnome.org or + else by emailing the + gnome-doc-list mailing list. + + + After an author has finished a document (or even a draft + version of the document), it is a good idea to ask a member of + the GDP team to read the document, checking it for grammar, + proper DocBook markup, and clarity. One may typically find + another author to do this by either asking on the #docs IRC + channel at irc.gnome.org or by emailing the + gnome-doc-list mailing list. + + + + + + + Working With Developers + + Writing documentation typically involves a certain amount of + interaction with the developers of GNOME or the application + which is being documented. Often a document author will need + to ask the developer technical questions during the course of + writing a document. After the document is finished, it is good + idea to ask the developer to read the document to make sure it + is technically correct. The documentation author should also + make sure that the application author correctly binds and + packages the documentation with the application. + + + + + + + + + + Finishing A Document + + + + + Editing The Document + + When the document is finished, the document should be edited + by another member of the GDP for spelling, clarity, and + DocBook markup. It should also be read by an application + author to make sure the document is technically accurate. + + + + + + + Submitting The Document + + After the document has been edited and checked for technical + accuracy, it is ready to be combined with the application or + documentation package. This is typically done by passing the + document to the application or package developer. In some + cases, the documents can be committed directly into CVS, + however this should only be done after obtaining permission to + make CVS commits from the developer. Note that in many cases, + the application may need to be modified to correctly link to + the documentation. The packaging system (tarballs and binary + packages) may also need to be modified to include the + documentation in the package. Generally, this should be done + by the developers. + + + The final step is to email the GNOME Translation Team at + gnome-i18n@nuclecu.unam.mx to notify them that + there is a new document for them to translate. + + + + + + + + Resources + + + + Resources On The Web The GNOME + Documentation Project Web page lists current GDP + projects and members. + + + The GDP Documentation Status Table tracks the + status of all the various documentation components of GNOME. + + + Norman Walsh's DocBook: The Definitive + Guide in an excellent book on DocBook, + available both online and in print. + + + + + + + Books + + Docbook: The Definitive Guide is available in both printed + form and on the web at: + + Docbook: The Definitive Guide + + + + + + + + Mailing Lists + + The gnome-docs-list mailing list is the + main discussion area for all contributors to the GNOME + Documentation Project. You can find out how to subscribe to + this list on GNOME Mailing Lists. This is a rather + low-volume list, so you will not be flooded with messages. + + + + + + + IRC + + Internet Relay Chat (IRC) is a fast and easy way to get in + touch with other GDP members. There are generally at least a + few members here who can answer questions or discuss + documentation issues. The IRC channel is #docs at + irc.gnome.org. + + + + + + + + + + Document Templates + + + + Template 1: Application Manual + + The following template should be used for all application + manuals. You can always get the latest copy of this + template from GDP + Documentation Templates. + + + + + + +]> + + + + + + +
+ + + MY-GNOME-APP + + 2000 + ME-THE-AUTHOR + + + + + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free + Documentation License, Version 1.1 or any later + version published by the Free Software Foundation with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. You may obtain a copy of the GNU Free + Documentation License from the Free Software + Foundation by visiting their Web site or by writing + to: Free Software Foundation, Inc., 59 Temple Place - Suite + 330, Boston, MA 02111-1307, USA. + + + Many of the names used by companies to distinguish their + products and services are claimed as trademarks. Where those + names appear in any GNOME documentation, and those trademarks + are made aware to the members of the GNOME Documentation + Project, the names have been printed in caps or initial caps. + + + + + + This is version 1.0 of MY-GNOME-APP manual. + + + + + + + + + Introduction + + + MY-GNOME-APP is an application which + proves mathematical theorems. It has all the basic features + expected from a mathematical theorem prover, as well as a number + of advanced ones, such as proof by confusion. In fact, many of + the proofs produced by MY-GNOME-APP + are so complex that they are capable of proving almost anything + with a virtually null likelihood of being disproven. It also has + the very popular predecessor of proof by confusion, proof by + dialog, first implemented by Plato. + + + It also allows you to save and print theorem proofs and to add + comments to the proofs it produces. + + + + To run MY-GNOME-APP, select + + SUBMENU + MY-GNOME-APP + + from the Main Menu, or type + MYGNOMEAPP on the command line. + + + + MY-GNOME-APP is included in the + GNOME-PACKAGE package, which is part of the + GNOME desktop environment. This document describes version + &version; of MY-GNOME-APP. + + + + + + + + + Using MY-GNOME-APP + + MY-GNOME-APP can be used to produce a + perfect proof of any mathematical theorem + (provided, of course, that this theorem is correct), thus + providing for new users an easy-to-use graphical interface to + modern mathematics. This section describes basic usage of + MY-GNOME-APP. + + + + + Basic usage + + Starting MY-GNOME-APP opens the + Main window, shown in . The window is at first empty. + + +
+ MY-GNOME-APP Main Window + + MY-GNOME-APP Main Window + + + +
+ + + + + + + + Proving a Theorem + + To get a proof of a theorem, select + + File + New + , + which will + bring up the New Proof dialog box. + Enter the statement of the theorem in the + Theorem statement field, select your + desired proof type from the drop-down menu, and and press + Prove!. + + + If MY-GNOME-APP cannot prove the + theorem by the method you have chosen, or if you have not + selected a proof type at all, + MY-GNOME-APP will attempt to + choose the one that it thinks is most conclusive. In order, + it will attempt to prove the theorem with the following techniques: + + + + Deduction + + + This is a proof method that is generally accepted + for full credit by Logic professors. + + + + + Induction + + + This logical style will also earn you full credit on + your homework. + + + + + Dialog + + + This logical method is best for Philosophy classes, + and will probably only merit partial credit on Logic + or Mathematics homework. + + + + + Confusion + + + Suitable only for political debates, battles of wits + against the unarmed, and Philosophy classes focusing + on the works of Kant. Use with caution. + + + + + + + + + + Proving Incorrect Theorms + + MY-GNOME-APP cannot prove + incorrect theorems. If the theorem you have entered is not + demonstrably true, you will get a message to that effect + in the main window. To disprove a theorem, ask + MY-GNOME-APP to prove its + logical inverse. + + + + + Editing Proofs + + Once you have proven the theorem, it will be displayed in + the main window. There, you can read + it over, choose text styles for different portions of it, + and make comments on it. This section will guide you through + that process. + + + To alter text styles, first select the statement you wish to + change by clicking on it once. You can select several + statements by Then, choose the style you want to apply from + the Style submenu of the + Edit menu. + MY-GNOME-APP will convert the + text to that style. + + + You can also enter comments on a statement by selecting that + statement, and then beginning to type. Comments will appear + after the statement you have selected. + + + + Altering The Proofs Themselves + + MY-GNOME-APP does not allow you + to alter a proof it has produced itself. You can, save + your proof as a plain text file (using the + Save as... menu), and alter it + that way. Be aware, however, that + MY-GNOME-APP uses its own file + format for saved proofs, and cannot re-open a file unless + it is in the .mga format. + + + + + + + + + + + + + + Toolbar + + The toolbar (shown in ) + provides access to several commonly used routines. +
+ MY-GNOME-APP Toolbar + + MY-GNOME-APP Toolbar + + +
+ + + New + + + Brings up the New Theorem + dialog. + + + + + Open + + + Open an exisiting theorem you want to prove, or a + completed proof you wish to print or format. + + + + + Save + + + Save the current theorem permanently in a + file. + + + + + + + + + + + + + Menus + + The menu bar, located at the top of the Main + Window, contains the following menus: + + + + File + + + This menu contains: + + + + + + F3 + + Open + + — This opens a file which is saved on your computer. + + + + + + + CtrlS + + Save + + — This saves your file. + + + + + + + CtrlW + + Close + + — This closes your file. + + + + + + + CtrlQ + + Exit + + — This quits the application. + + + + + + + + + Edit + + + This menu contains: + + + + + + CtrlX + + Cut + + — This removes any text or data which is selected and + places it in the buffer. + + + + + + + CtrlC + + Copy + + — This copies any text or data which is selected into + the buffer. + + + + + + + CtrlV + + Paste + + — This pastes any text or data which is copied into + the buffer. + + + + + COMMAND1… + — This opens the COMMAND1 + dialog, which is used to .... + + + + + COMMAND2 + — This .... + + + + + + + + + + Settings + + + This menu contains: + + + + Preferences… + — This opens the Preferences + Dialog, which allows you to configure + many settings. + + + + + COMMAND3 — + This command does something. + + + + + + + + + Help + + + This menu contains: + + + + Manual — This + opens the GNOME Help + Browser and displays this manual. + + + + + + About — This + opens the About dialog + which shows basic information about + MY-GNOME-APP, such as + the author's name, the application version number, + and the URL for the application's Web page if one + exists. + + + + + + + + + + + + + + + + Customization + + To change the application settings, select + + Settings + Preferences... + . This opens the + Preferences dialog, shown in . + + +
+ Preferences Dialog + + Preferences Dialog + + + +
+ + + The properties in the PREFSTABNAME tab are: + + + + + + Default Text Style + + + Select the default text style for statements in your + proof. You can still change the style for individual + proofs or sections of a proof at a later date. + + + + + (Configuration Item Label) + + + (Description of Configuration) + + + + + (Configuration Item Label) + + + (Description of Configuration) + + + + + + + + The properties in the SECONDTABNAME tab are: + + + (Configuration Item Label) + + + (Description of Configuration) + + + + + (Configuration Item Label) + + + (Description of Configuration) + + + + + + + + After you have made all the changes you want, click on + OK to apply the changes and close the + Properties dialog. To cancel the changes + and return to previous values, click the + Close button. + + + + + + + + + + + + + + Known Bugs and Limitations + + This application has no known bugs. + + + + + + + + Authors + + MY-GNOME-APP was written by GNOME-HACKER + (hacker@gnome.org). To find more information about + MY-GNOME-APP, please visit the MY-GNOME-APP Web + page. Please send all comments, suggestions, and bug + reports to the GNOME + bug tracking database. (Instructions for submitting bug + reports can be found + on-line.) You can also use Bug Report + Tool (bug-buddy), available in the + Utilities submenu of Main + Menu, for submitting bug reports. + + + + This manual was written by ME + (MYNAME@MYADDRESS). Please send all comments and + suggestions regarding this manual to the GNOME Documentation + Project by sending an email to + docs@gnome.org. You can also add your comments online + by using the GNOME Documentation Status + Table. + + + + + + + + + + + License + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any later + version. + + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + + A copy of the GNU General Public License is + included as an appendix to the GNOME Users + Guide. You may also obtain a copy of the + GNU General Public License from the Free + Software Foundation by visiting their Web site or by writing to +
+ Free Software Foundation, Inc. + 59 Temple Place - Suite 330 + Boston, MA 02111-1307 + USA +
+ + +
+ + + + + + + + + +]]> + + + + + + + + + + Template 2: Applet Manual For GNOME 1.x + + The following templates should be used for all applet + manuals in GNOME 1.x releases. You can always get the latest + copy of these templates from GDP + Documentation Templates. Note that the template + consists of two files; the first file calls the second as an + entity. You should name the first file + appletname-applet.sgml + and the second file should be named + appletname.sgml, + where + appletname is + the name of the applet. + + + + +]> + + + +
+ + + + APPLETNAME Applet + + 2000 + YOURFULLNAME + + + + + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.1 or any later version published + by the Free Software Foundation with no Invariant Sections, no + Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy + of the GNU Free Documentation License from + the Free Software Foundation by visiting their Web site or by writing to: + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + + + Many of the names used by companies to distinguish their products and + services are claimed as trademarks. Where those names appear in any + GNOME documentation, and those trademarks are made aware to the members + of the GNOME Documentation Project, the names have been printed in caps + or initial caps. + + + + + This is version XXX of the APPLETNAME applet manual. + + + + + + &APPLETNAME.sgml; + +
+ + +]]> + + + + + + + + APPLET Applet + + + APPLET applet, shown in , allows you to …. To add this + applet to a Panel, + right-click on the Panel and choose + + Panel + Add to panel + Applet + SECTION + APPLET + . + + +
+ APPLET Applet + + APPLET Applet + + + +
+ + + + Usage + + (Place a short description of how to use the applet here.) + + + + Right-clicking on the applet brings up a menu containing the + following items: + + + + + Properties… — + opens the + Properties dialog. + + + + + + Help — + displays this document. + + + + + + About… — + shows basic information about APPLET + Applet, including the applet's version and the + author's name. + + + + + + + + + + + Customization + + You can customize APPLET + applet by right-clicking on it and choosing + Properties…. This will open the + Properties dialog(shown in ), which allows you to + change various settings. + + +
+ Properties dialog + + Properties dialog + + + +
+ + + The properties are: + + + + + (Configuration Item Label) — If this button is + checked…(description) + + + + + + (Configuration Item Label) — Selecting this + button…(description) + + + + + + (Configuration Item Label) — Enter the name of + …(description) + + + + + + + After you have made all the changes you want, click on + OK to apply the changes and close the + Properties dialog. To cancel the changes + and return to previous values, click the + Close button. + + + + + + + + Known Bugs and Limitations + + This applet has no known bugs. + + + + + + + + Authors + + APPLET was written by GNOME-HACKER + (hacker@gnome.org). Please send all comments, + suggestions, and bug + reports to the GNOME + bug tracking database. (Instructions for submitting bug + reports can be found + on-line. You can also use Bug Report + Tool (bug-buddy), available in the + Utilities submenu of Main + Menu, for submitting bug reports. + + + + This manual was written by ME + (MYNAME@MYADDRESS). Please send all comments and + suggestions regarding this manual to the GNOME Documentation + Project by sending an email to + docs@gnome.org. You can also submit comments online + by using the GNOME Documentation + Status Table. + + + + + + + + + + + License + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; + either version 2 of the License, or (at your option) any later + version. + + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + + A copy of the GNU General Public License is + included as an appendix to the GNOME Users + Guide. You may also obtain a copy of the + GNU General Public License from the Free + Software Foundation by visiting their Web site or by writing to +
+ Free Software Foundation, Inc. + 59 Temple Place - Suite 330 + Boston, MA 02111-1307 + USA +
+ + + + + + + + +]]> + + + + + + + + + + + Template 2: Applet Manual For GNOME 2.x + + The following templates should be used for all applet + manuals in GNOME 2.x releases. You can always get the latest + copy of these templates from GDP + Documentation Templates. + + + Note that this template consists of two files. The first file + is an introductory chapter. You should not modify this + chapter. The second file is the actual applet document, which + you should modify to describe the applet you are documenting. + You can name the first file whatever you like, such as + gnome-applets.sgml. Name the second file + according to the applet's name: + appletname-applet.sgml. + Make sure you update the entity + at the top of the shell document to reflect the new name of + the applet document. + + + + + +]> + + + + + GNOME Applets + + TelsaGwynne + JohnFleck + DavidMason + Red Hat, Inc. + + DanMueth + AlexanderKirillov + + GNOME Applets version 0.1 for GNOME 1.1.5 + 2000 + + 2000 + Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and + Alexander Kirillov + + + + Permission is granted to make and distribute verbatim copies of this + manual provided the copyright notice and this permission notice are + preserved on all copies. + + + Permission is granted to copy and distribute modified versions of + this manual under the conditions for verbatim copying, provided that + the entire resulting derived work is distributed under the terms of a + permission notice identical to this one. + + + Permission is granted to copy and distribute translations of this + manual into another language, under the above conditions for modified + versions, except that this permission notice may be stated in a + translation approved by the Free Software Foundation. + + + Many of the names used by companies to distinguish their products and + services are claimed as trademarks. Where those names appear in any + GNOME documentation, and those trademarks are made aware to the members + of the GNOME Documentation Project, the names have been printed in caps + or initial caps. + + + + + + + Introduction + + + + What Are Applets? + + Applets are one of the most popular and useful objects you can add + to your Panel to customize your desktop. + An applet is a small application which runs inside a small area of + your Panel. Applets have been written for + a wide range of purposes. Some are very powerful interactive + tools, such as the Tasklist Applet + which allows you to easily + control all of your main applications. Others are simple system + monitors, displaying information such as the amount of power left + in the battery on your laptop (see Battery Charge + Monitor) or weather + information(see GNOME Weather). Some + are simply for amusement(see Fish). + + + + Applets are similar to swallowed applications in that both of them + reside within the Panel. However, + swallowed applications are generally applications which were + not designed to run within the Panel. + Typically one will swallow an application which already exists in + the main desktop area, putting it into your + Panel. The application will continue to + run in the Panel until you end the + application or unswallow it, placing it back onto the main part of + your desktop when you need to. + + + +
+ Example Applets + + Example Applets + + + +
+ Several example applets are shown in . From left to right, they are: (1) + Mixer Applet, which allows you to turn + on/off sound and control its volume by clicking on the applet. (2) + Sound Monitor Applet, which displays + the current volume of sound being played and allows you to control + various sound features. (3) GTCD + Applet, a CD player which has all its controls + available in the applet and displays the track and time. (4) + Drive Mount Applet, used to mount and + unmount drives with a single click of the mouse. (5) + Desk Guide which allows you to view + and control multiple virtual screens. (6) + Tasklist Applet which allows you to + control your various windows and applications. + + + There are many other applets to choose from. The rest of this + chapter will explain the basic information to get you started + adding, moving, and removing applets from your + Panels and using them. The following + chapters go through each of the standard GNOME applets describing + them in detail. There are also additional applets which can be + downloaded off the Web. See The GNOME + Software Map for lists of additional GNOME applications + and applets. + + + As you read through the the rest of this chapter, you should try + adding and removing applets from your Panel and + experiment with them freely. + + + + + + Adding, Moving, and Removing Applets + + + Adding Applets to a Panel + + To add an applet to a Panel, right-click + on the Panel and select + PanelAdd to panel + Applet. This will show you + the menu of all the applets on your system, divided into + categories. Choosing any applet from this menu will add it to the + Panel. + + + + + Moving Applets In or Between Panels + + It is easy to move applets in a Panel or + between two Panels. If you have a + three-button mouse, just move the mouse over the applet, depress + the middle mouse button and drag the applet to its new location, + releasing the middle mouse button when you are finished. Note + that you can drag applets within a Panel + or between two Panels this way. If you + don't have a three-button mouse, just + right-click on the applet and choose + Move. The cursor will turn into a + cross and the applet will move with your mouse until you press + any mouse button to indicate you are finished moving it. + If, in the course of this movement, it hits + other objects, the behavior depends on the global preferences + you have set for your Panels in the + GNOME Control Center: the applet you are + moving can switch places with other objects, "push" all objects + it meets, or "jump" over all other objects without disturbing + them. You can also override the default behavior by holding + Shift button (for "push" mode), + Ctrl (for "switched" mode), or + Alt (for "free" mode, i.e. jumping other other + objects without disturbing them) button while dragging. + + + To change the global Panel preferences, right-click on any applet + or Panel and select + + Panel + Global Preferences... + . + The Default movement mode is set under the + Applets tab. + + + + + Removing Applets from a Panel + + To remove an applet from a Panel, + right-click on the applet and select Remove from + panel.... + + + + + + + + The Right-Click Pop-Up Menu + + Clicking the right mouse button on any applet brings up + a pop-up menu. This + menu always has certain standard menu items in it and + often has additional items which vary depending on the particular + applet. + + + Standard Pop-Up Items + + All applets should have the following items in their right-click + pop-up menu: + + + Remove from panel + + + The Remove from panel menu item + removes the applet from the Panel. + + + + + + Move + + + After selecting Move, your mouse + pointer will change appearance (typically to a cross with + arrows in each direction). As you move your mouse, the applet + will move with it. When you have finished moving the applet, + click any mouse button and the applet will anchor in its + current position. Note that applets can be moved between two + Panels this way. + + + + + + Panel + + + The Panel submenu contains various + items and submenus for adding and removing + Panels and applets and for changing + the configuration. + + + + + + About + + + The About... menu item brings up a + dialogue box containing various information about the applet, + typically including the applet's name, version, author, + copyright, license and desciption. + + + + + + Help + + + The Help menu item brings up the help + manual for the applet. + + + + + + + + + The Applet Properties Dialog + + Many applets have customizable properties. These applets will + have a Properties... menu item in their + right-click pop-up menu which brings up the + Properties dialog where you can alter the + appearance or behaviour of the applet. +
+ An Example Applet Properties Dialog + + An Example Applets Properties Dialog + + + +
+ All Properties dialogs have the following + buttons at the bottom of the dialog: + + + + OK — + Pressing OK will activate any changes + in the properties you have made and close the + Properties dialog. + + + + + Apply — + Pressing Apply at any time will + make your changes active without closing the + Properties dialog. This is helpful if + you would like to test the effects of the changes you have + made but may want to continue changing the properties. + + + + + Close — + Pressing Close will close the + Properties dialog. Only changes in the + configuration which were previously applied with the + Apply button will persist. Other + changes will not be made active. + + + + + Help — + Pressing Help brings up the manual for + the application, opening it to the page describing the + Properties dialog. + + + + + + + + Other Common Pop-Up Items + + Many applets also have one or more of the following items in their + right-click pop-up menu: + + + Run... + + + The Run... menu item generally + invokes a program which is related to the applet in some way + but which runs in its own window rather than in the + panel. For example: + + + + + The CPU Load applet, which monitors + what programs are running, has a Run + gtop... menu item. Selecting this menu item + starts GTop, which allows you to + view and control programs which are running. + + + + + The CD Player applet has a + Run gtcd... menu item which + starts the GNOME CD Player when + selected, which has more capabilities than the applet. + + + + + + + + + + + + Feedback + + Reporting Applet Bugs + + GNOME users are encouraged to report bugs to The GNOME Bug Tracking + System. The easiest way to submit bugs is to use the + Bug Report Tool program by selecting + + Main Menu Utilities + Bug Report Tool + . + Be sure to be complete in describing what you did to cause the + bug to surface and, if possible, describe how the developer can + reproduce the the scenario. + + + + Providing Feedback + + GNOME users are welcome to provide suggestions for how + applications and documentation can be improved. Suggestions for + application changes should be submitted using the + Bug Report Tool discussed above. + Suggestions for documentation changes can be emailed directly to + the documentation author (whose email should be included in the + "Authors" section of the document) or by sending an email to + docs@gnome.org. + + + + Joining GNOME + + GNOME is a community project, created by hundreds of programmers, + documentation writers, icon design artists, web masters, and + other people, most of whom work on a volunteer basis. New GNOME + contributors are always welcome. To join the GNOME team, visit + these web sites: developers — The GNOME Development + Site, documentation writers — The GNOME Documentation + Project, icon design artists — Gnome Icon Web, + general — Helping GNOME, + or just join the gnome-list email list (see GNOME Mailing + Lists) to discuss what you are interested in doing. + + + + + + + + Template Applets + + &TEMPLATE-APPLET + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GNOMEAPPLET Applet + + + GNOMEAPPLET applet, shown in , does this and that. To learn how to + add this applet to a Panel, see . + + + +
+ GNOMEAPPLET + + GNOMEAPPLET + + + +
+ + + Usage + + This applet does nothing. To use it, just + left-click on it and it will instantly do nothing. + + + + + Right-Click Pop-Up Menu Items + + In addition to the standard menu items (see ), the right-click pop-up menu has + the following items: + + + + Properties... — This menu + item opens the Properties dialog (see + ) which allows you to + customize the appearance and behavior of this applet. + + + + + Run Hello World... — This + menu item starts the program Hello + World, used to say "hello" to the world. + + + + + + + + Properties + + You can configure GNOMEAPPLET applet by + right-clicking on the applet and choosing the + Properties... menu item. This will open the + Properties dialog, shown in . + +
+ Properties Dialog + + Properties Dialog + + + +
+ + + To change the color of the applet, click on the + color button. To change other properties, + click on other buttons. + + + + For more information on the Properties + dialog, including descriptions of the OK, + Apply, Cancel, and + Help buttons, see . + + + + + Known Bugs and Limitations + + There are no known bugs in the + GNOMEAPPLET applet. + + + + + Authors + + This applet was writen by HACKER-NAME + HACKER-EMAIL. The documentation for this applet + which you are reading now was written by + YOUR-NAME YOUR-EMAIL. For information on submitting + bug reports and suggestions for improvements, see . + + + + + + + + + +]]> + + + + + + + + + +
diff --git a/test/relaxng/proofsystem.rng b/test/relaxng/proofsystem.rng new file mode 100644 index 00000000..7fe6bd36 --- /dev/null +++ b/test/relaxng/proofsystem.rng @@ -0,0 +1,96 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/test/relaxng/spec.rng b/test/relaxng/spec.rng new file mode 100644 index 00000000..9650f711 --- /dev/null +++ b/test/relaxng/spec.rng @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/test/relaxng/spec_0.xml b/test/relaxng/spec_0.xml new file mode 100644 index 00000000..cb8f7be5 --- /dev/null +++ b/test/relaxng/spec_0.xml @@ -0,0 +1,3589 @@ + + + + + + + + +]> +
+ + +$Id: spec.xml,v 1.159 2001/12/02 12:12:12 jjc Exp $ +RELAX NG Specification + + + JamesClark + +
jjc@jclark.com
+ + + + MURATAMakoto + +
EB2M-MRT@asahi-net.or.jp
+ + + +3 December 2001 + +$Id: spec.xml,v 1.159 2001/12/02 12:12:12 jjc Exp $ + + +2001OASIS + + + +Copyright © The Organization for the Advancement of +Structured Information Standards [OASIS] 2001. All Rights +Reserved. + +This document and translations of it may be copied and furnished +to others, and derivative works that comment on or otherwise explain +it or assist in its implementation may be prepared, copied, published +and distributed, in whole or in part, without restriction of any kind, +provided that the above copyright notice and this paragraph are +included on all such copies and derivative works. However, this +document itself may not be modified in any way, such as by removing +the copyright notice or references to OASIS, except as needed for the +purpose of developing OASIS specifications, in which case the +procedures for copyrights defined in the OASIS Intellectual Property +Rights document must be followed, or as required to translate it into +languages other than English. + +The limited permissions granted above are perpetual and will not +be revoked by OASIS or its successors or assigns. + +This document and the information contained herein is provided +on an AS IS basis and OASIS DISCLAIMS ALL WARRANTIES, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE +USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY +IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE. + + + +Status of this Document + +This Committee Specification was approved for publication by the +OASIS RELAX NG technical committee. It is a stable document which +represents the consensus of the committee. Comments on this document +may be sent to relax-ng-comment@lists.oasis-open.org. + +A list of known errors in this document is available at http://www.oasis-open.org/committees/relax-ng/spec-20011203-errata.html. + + + + +This is the definitive specification of RELAX NG, a simple +schema language for XML, based on and . A RELAX NG schema specifies a pattern for the +structure and content of an XML document. A RELAX NG schema is itself +an XML document. + + + + + Committee Specification + 3 December 2001 + + + Committee Specification + 11 August 2001 + + + + + +
+Introduction + +This document specifies + + + +when an XML document is a correct RELAX NG +schema + +when an XML document is valid with respect to a +correct RELAX NG schema + + + +An XML document that is being validated with respect to a RELAX NG +schema is referred to as an instance. + +The structure of this document is as follows. describes the data model, which is the +abstraction of an XML document used throughout the rest of the +document. describes the syntax of a +RELAX NG schema; any correct RELAX NG schema must conform to this +syntax. describes a sequence of +transformations that are applied to simplify a RELAX NG schema; +applying the transformations also involves checking certain +restrictions that must be satisfied by a correct RELAX NG +schema. describes the syntax that +results from applying the transformations; this simple syntax is a +subset of the full syntax. describes the +semantics of a correct RELAX NG schema that uses the simple syntax; +the semantics specify when an element is valid with respect to a RELAX +NG schema. describes restrictions in +terms of the simple syntax; a correct RELAX NG schema must be such +that, after transformation into the simple form, it satisfies these +restrictions. Finally, describes +conformance requirements for RELAX NG validators. + +A tutorial is available separately (see ). + +
+ +
+Data model + +RELAX NG deals with XML documents representing both schemas and +instances through an abstract data model. XML documents representing +schemas and instances must be well-formed in conformance with and must conform to the constraints of . + +An XML document is represented by an element. An element consists +of + + + +a name + +a context + +a set of attributes + +an ordered sequence of zero or more children; each +child is either an element or a non-empty string; the sequence never contains +two consecutive strings + + + +A name consists of + + +a string representing the namespace URI; the empty +string has special significance, representing the absence of any +namespace + +a string representing the local name; this string matches the NCName +production of + + +A context consists of + + +a base URI +a namespace map; this maps prefixes to namespace URIs, +and also may specify a default namespace URI (as declared +by the xmlns attribute) + + +An attribute consists of + + +a name +a string representing the value + + +A string consists of a sequence of zero or more characters, +where a character is as defined in . + +The element for an XML document is constructed from an instance +of the as follows. We use the notation +[x] to refer to the value of the +x property of an information item. An +element is constructed from a document information item by +constructing an element from the [document element]. An element is +constructed from an element information item by constructing the name +from the [namespace name] and [local name], the context from the [base +URI] and [in-scope namespaces], the attributes from the [attributes], +and the children from the [children]. The attributes of an element +are constructed from the unordered set of attribute information items +by constructing an attribute for each attribute information item. The +children of an element are constructed from the list of child +information items first by removing information items other than +element information items and character information items, and then by +constructing an element for each element information item in the list +and a string for each maximal sequence of character information items. +An attribute is constructed from an attribute information item by +constructing the name from the [namespace name] and [local name], and +the value from the [normalized value]. When constructing the name of +an element or attribute from the [namespace name] and [local name], if +the [namespace name] property is not present, then the name is +constructed from an empty string and the [local name]. A string is +constructed from a sequence of character information items by +constructing a character from the [character code] of each character +information item. + +It is possible for there to be multiple distinct infosets for a +single XML document. This is because XML parsers are not required to +process all DTD declarations or expand all external parsed general +entities. Amongst these multiple infosets, there is exactly one +infoset for which [all declarations processed] is true and which does +not contain any unexpanded entity reference information items. This +is the infoset that is the basis for defining the RELAX NG data +model. + +
+Example + +Suppose the document +http://www.example.com/doc.xml is as +follows: + + + +]]> + +The element representing this document has + + +a name which has + + +the empty string as the namespace URI, representing +the absence of any namespace + +foo as the local +name + + + + + +a context which has + + +http://www.example.com/doc.xml as the base +URI + +a namespace map which + + + +maps the prefix xml to the +namespace URI +http://www.w3.org/XML/1998/namespace +(the xml prefix is implicitly declared +by every XML document) + +specifies the empty string as the default namespace +URI + + + + + + + + + +an empty set of attributes + +a sequence of children consisting +of an element which has + + +a name which has + + +http://www.example.com/n1 as the +namespace URI + +bar1 as the local +name + + + + + +a context which has + + +http://www.example.com/doc.xml as the base +URI + +a namespace map which + + + +maps the prefix pre1 to the +namespace URI +http://www.example.com/n1 + +maps the prefix xml to the +namespace URI +http://www.w3.org/XML/1998/namespace + +specifies the empty string as the default namespace +URI + + + + + + + + + +an empty set of attributes + +an empty sequence of children + + + +followed by an element which has + + +a name which has + + +http://www.example.com/n2 as the +namespace URI + +bar2 as the local +name + + + + + +a context which has + + +http://www.example.com/doc.xml as the base +URI + +a namespace map which + + + +maps the prefix pre2 to the +namespace URI +http://www.example.com/n2 + +maps the prefix xml to the +namespace URI +http://www.w3.org/XML/1998/namespace + +specifies the empty string as the default namespace +URI + + + + + + + + + +an empty set of attributes + +an empty sequence of children + + + + + + +
+ +
+ +
+Full syntax + +The following grammar summarizes the syntax of RELAX NG. +Although we use a notation based on the XML representation of an RELAX +NG schema as a sequence of characters, the grammar must be understood +as operating at the data model level. For example, although the +syntax uses ]]>, an instance or +schema can use ]]> instead, +because they both represent the same element at the data model level. +All elements shown in the grammar are qualified with the namespace +URI: + +http://relaxng.org/ns/structure/1.0 + +The symbols QName and NCName are defined in . The anyURI symbol has the same meaning as the +anyURI datatype of : it indicates a +string that, after escaping of disallowed values as described in +Section 5.4 of , is a URI reference as defined +in (as modified by ). The symbol string matches any string. + +In addition to the attributes shown explicitly, any element can +have an ns attribute and any element can have a +datatypeLibrary attribute. The +ns attribute can have any value. The value of the +datatypeLibrary attribute must match the anyURI +symbol as described in the previous paragraph; in addition, it must +not use the relative form of URI reference and must not have a +fragment identifier; as an exception to this, the value may be the +empty string. + +Any element can also have foreign attributes in addition to the +attributes shown in the grammar. A foreign attribute is an attribute +with a name whose namespace URI is neither the empty string nor the +RELAX NG namespace URI. Any element that cannot have string children +(that is, any element other than value, param +and name) may have foreign child elements in addition +to the child elements shown in the grammar. A foreign element is an +element with a name whose namespace URI is not the RELAX NG namespace +URI. There are no constraints on the relative position of foreign +child elements with respect to other child elements. + +Any element can also have as children strings that consist +entirely of whitespace characters, where a whitespace character is one +of #x20, #x9, #xD or #xA. There are no constraints on the relative +position of whitespace string children with respect to child +elements. + +Leading and trailing whitespace is allowed for value of each +name, type and +combine attribute and for the content of each +name element. + + + +
+Example + +Here is an example of a schema in the full syntax for the +document in . + + + + A foo element. + + + + + + +]]> + +
+ +
+ +
+Simplification + +The full syntax given in the previous section is transformed +into a simpler syntax by applying the following transformation rules +in order. The effect must be as if each rule was applied to all +elements in the schema before the next rule is applied. A +transformation rule may also specify constraints that must be +satisfied by a correct schema. The transformation rules are applied +at the data model level. Before the transformations are applied, the +schema is parsed into an instance of the data model. + +
+Annotations + +Foreign attributes and elements are removed. + +It is safe to remove xml:base +attributes at this stage because xml:base +attributes are used in determining the [base URI] of an element +information item, which is in turn used to construct the base URI of +the context of an element. Thus, after a document has been parsed +into an instance of the data model, xml:base +attributes can be discarded. + +
+ +
+Whitespace + +For each element other than value and +param, each child that is a string containing only +whitespace characters is removed. + +Leading and trailing whitespace characters are removed from the +value of each name, type and +combine attribute and from the content of each +name element. + +
+ +
+<literal>datatypeLibrary</literal> attribute + +The value of each datatypeLibary attribute is +transformed by escaping disallowed characters as specified in Section +5.4 of . + +For any data or value +element that does not have a datatypeLibrary +attribute, a datatypeLibrary attribute is +added. The value of the added datatypeLibrary +attribute is the value of the datatypeLibrary +attribute of the nearest ancestor element that has a +datatypeLibrary attribute, or the empty string if +there is no such ancestor. Then, any datatypeLibrary +attribute that is on an element other than data or +value is removed. + +
+ +
+<literal>type</literal> attribute of <literal>value</literal> element + +For any value element that does not have a +type attribute, a type attribute +is added with value token and the value of the +datatypeLibrary attribute is changed to the empty +string. + +
+ +
+<literal>href</literal> attribute + +The value of the href attribute on an +externalRef or include element +is first transformed by escaping disallowed characters as specified in +Section 5.4 of . The URI reference is then +resolved into an absolute form as described in section 5.2 of using the base URI from the context of the element +that bears the href attribute. + +The value of the href attribute will be used +to construct an element (as specified in ). This must be done as follows. The URI +reference consists of the URI itself and an optional fragment +identifier. The resource identified by the URI is retrieved. The +result is a MIME entity: a sequence of bytes labeled with a MIME +media type. The media type determines how an element is constructed +from the MIME entity and optional fragment identifier. When the media +type is application/xml or +text/xml, the MIME entity must be parsed as an XML +document in accordance with the applicable RFC (at the term of writing +) and an element constructed from the result +of the parse as specified in . In +particular, the charset parameter must be handled +as specified by the RFC. This specification does not define the +handling of media types other than application/xml +and text/xml. The href attribute +must not include a fragment identifier unless the registration of the +media type of the resource identified by the attribute defines the +interpretation of fragment identifiers for that media type. + + does not define the +interpretation of fragment identifiers for +application/xml or +text/xml. + +
+ +
+<literal>externalRef</literal> element + +An externalRef element is transformed as +follows. An element is constructed using the URI reference that is +the value of href attribute as specified in . This element must match the syntax for pattern. The +element is transformed by recursively applying the rules from this +subsection and from previous subsections of this section. This must +not result in a loop. In other words, the transformation of the +referenced element must not require the dereferencing of an +externalRef attribute with an +href attribute with the same value. + +Any ns attribute on the +externalRef element is transferred to the +referenced element if the referenced element does not already have an +ns attribute. The externalRef +element is then replaced by the referenced element. + +
+ +
+<literal>include</literal> element + +An include element is transformed as follows. +An element is constructed using the URI reference that is the value of +href attribute as specified in . This element must be a grammar +element, matching the syntax for grammar. + +This grammar element is transformed by +recursively applying the rules from this subsection and from previous +subsections of this section. This must not result in a loop. In other +words, the transformation of the grammar element +must not require the dereferencing of an include +attribute with an href attribute with the same +value. + +Define the components of an element to +be the children of the element together with the components of any +div child elements. If the +include element has a start +component, then the grammar element must have a +start component. If the include +element has a start component, then all +start components are removed from the +grammar element. If the include +element has a define component, then the +grammar element must have a +define component with the same name. For every +define component of the include +element, all define components with the same name +are removed from the grammar element. + +The include element is transformed into a +div element. The attributes of the +div element are the attributes of the +include element other than the +href attribute. The children of the +div element are the grammar +element (after the removal of the start and +define components described by the preceding +paragraph) followed by the children of the include +element. The grammar element is then renamed to +div. + +
+ +
+<literal>name</literal> attribute of <literal>element</literal> +and <literal>attribute</literal> elements + +The name attribute on an +element or attribute element is +transformed into a name child element. + +If an attribute element has a +name attribute but no ns +attribute, then an ns="" attribute is added to the +name child element. + +
+ +
+<literal>ns</literal> attribute + +For any name, nsName or +value element that does not have an +ns attribute, an ns attribute is +added. The value of the added ns attribute is the +value of the ns attribute of the nearest ancestor +element that has an ns attribute, or the empty +string if there is no such ancestor. Then, any ns +attribute that is on an element other than name, +nsName or value is +removed. + +The value of the ns attribute is +not transformed either by escaping +disallowed characters, or in any other way, because the value of the +ns attribute is compared against namespace URIs in +the instance, which are not subject to any +transformation. + +Since include and +externalRef elements are resolved after +datatypeLibrary attributes are added but before +ns attributes are added, ns +attributes are inherited into external schemas but +datatypeLibrary attributes are not. + +
+ +
+QNames + +For any name element containing a prefix, the +prefix is removed and an ns attribute is added +replacing any existing ns attribute. The value of +the added ns attribute is the value to which the +namespace map of the context of the name element +maps the prefix. The context must have a mapping for the +prefix. + +
+ +
+<literal>div</literal> element + +Each div element is replaced by its +children. + +
+ +
+Number of child elements + +A define, oneOrMore, +zeroOrMore, optional, list or +mixed element is transformed so that it has exactly +one child element. If it has more than one child element, then its +child elements are wrapped in a group +element. Similarly, an element element is transformed so +that it has exactly two child elements, the first being a name class +and the second being a pattern. If it has more than two child elements, +then the child elements other than the first are wrapped in a +group element. + +A except element is transformed +so that it has exactly one child element. If it has more +than one child element, then its child elements are wrapped +in a choice element. + +If an attribute element has only one child +element (a name class), then a text element is +added. + +A choice, group or +interleave element is transformed so that it has +exactly two child elements. If it has one child element, then it is +replaced by its child element. If it has more than two child +elements, then the first two child elements are combined into a new +element with the same name as the parent element and with the first +two child elements as its children. For example, + +<choice> p1 p2 p3 </choice> + +is transformed to + +<choice> <choice> p1 p2 </choice> p3 </choice> + +This reduces the number of child elements by one. The +transformation is applied repeatedly until there are exactly two child +elements. + +
+ +
+<literal>mixed</literal> element + +A mixed element is transformed into an +interleaving with a text element: + +<mixed> p </mixed> + +is transformed into + +<interleave> p <text/> </interleave> + +
+ +
+<literal>optional</literal> element + +An optional element is transformed into +a choice with empty: + +<optional> p </optional> + +is transformed into + +<choice> p <empty/> </choice> + +
+ +
+<literal>zeroOrMore</literal> element + +A zeroOrMore element is transformed into a choice +between oneOrMore and +empty: + +<zeroOrMore> p </zeroOrMore> + +is transformed into + +<choice> <oneOrMore> p </oneOrMore> <empty/> </choice> + +
+ +
+Constraints + +In this rule, no transformation is performed, but various +constraints are checked. + +The constraints in this section, unlike the constraints +specified in , can be checked without +resolving any ref elements, and are accordingly +applied even to patterns that will disappear during later stages of +simplification because they are not reachable (see ) or because of notAllowed +(see ). + +An except element that is a child of an +anyName element must not have any +anyName descendant elements. An +except element that is a child of an +nsName element must not have any +nsName or anyName descendant +elements. + +A name element that occurs as the first child +of an attribute element or as the descendant of the +first child of an attribute element and that has an +ns attribute with value equal to the empty string +must not have content equal to xmlns. + +A name or nsName element +that occurs as the first child of an attribute +element or as the descendant of the first child of an +attribute element must not have an +ns attribute with value +http://www.w3.org/2000/xmlns. + +The defines the namespace URI of +namespace declaration attributes to be +http://www.w3.org/2000/xmlns. + +A data or value element +must be correct in its use of datatypes. Specifically, the +type attribute must identify a datatype within the +datatype library identified by the value of the +datatypeLibrary attribute. For a +data element, the parameter list must be one that +is allowed by the datatype (see ). + +
+ +
+<literal>combine</literal> attribute + +For each grammar element, all +define elements with the same name are combined +together. For any name, there must not be more than one +define element with that name that does not have a +combine attribute. For any name, if there is a +define element with that name that has a +combine attribute with the value +choice, then there must not also be a +define element with that name that has a +combine attribute with the value +interleave. Thus, for any name, if there is more +than one define element with that name, then there +is a unique value for the combine attribute for +that name. After determining this unique value, the +combine attributes are removed. A pair of +definitions + +<define name="n"> + p1 +</define> +<define name="n"> + p2 +</define> + +is combined into + +<define name="n"> + <c> + p1 + p2 + </c> +</define> + +where c is the value of the +combine attribute. Pairs of definitions are +combined until there is exactly one define element +for each name. + +Similarly, for each grammar element all +start elements are combined together. There must +not be more than one start element that does not +have a combine attribute. If there is a +start element that has a combine +attribute with the value choice, there must not +also be a start element that has a +combine attribute with the value +interleave. + +
+ +
+<literal>grammar</literal> element + +In this rule, the schema is transformed so that its top-level +element is grammar and so that it has no other +grammar elements. + +Define the in-scope grammar for an +element to be the nearest ancestor grammar element. A +ref element refers to a +define element if the value of their +name attributes is the same and their in-scope +grammars are the same. A parentRef element +refers to a define element +if the value of their name attributes is the same +and the in-scope grammar of the in-scope grammar of the +parentRef element is the same as the in-scope +grammar of the define element. Every +ref or parentRef element must +refer to a define element. A +grammar must have a start child +element. + +First, transform the top-level pattern +p into +<grammar><start>p</start></grammar>. +Next, rename define elements so that no two +define elements anywhere in the schema have the +same name. To rename a define element, change the +value of its name attribute and change the value of +the name attribute of all ref +and parentRef elements that refer to that +define element. Next, move all +define elements to be children of the top-level +grammar element, replace each nested +grammar element by the child of its +start element and rename each +parentRef element to ref. + +
+ + +
+<literal>define</literal> and <literal>ref</literal> elements + +In this rule, the grammar is transformed so that every +element element is the child of a +define element, and the child of every +define element is an element +element. + +First, remove any define element that is not +reachable. A define element +is reachable if there is reachable ref element +referring to it. A ref element is reachable if it +is the descendant of the start element or of a +reachable define element. Now, for +each element element that is not the child of a +define element, add a define +element to the grammar element, and replace the +element element by a ref element +referring to the added define element. The value of +the name attribute of the added +define element must be different from value of the +name attribute of all other +define elements. The child of the added +define element is the element +element. + +Define a ref element to be +expandable if it refers to a +define element whose child is not an +element element. For each ref +element that is expandable and is a descendant of a +start element or an element +element, expand it by replacing the ref element by +the child of the define element to which it refers and +then recursively expanding any expandable ref +elements in this replacement. This must not result in a loop. +In other words expanding the replacement of a +ref element having a name with +value n must not require the expansion of +ref element also having a name +with value n. Finally, remove any +define element whose child is not an +element element. + +
+ +
+<literal>notAllowed</literal> element + +In this rule, the grammar is transformed so that a +notAllowed element occurs only as the child of +a start or element element. An +attribute, list, +group, interleave, +or oneOrMore element that has a +notAllowed child element is transformed into a +notAllowed element. A choice +element that has two notAllowed child elements is +transformed into a notAllowed element. A +choice element that has one +notAllowed child element is transformed into its +other child element. An except element that has a +notAllowed child element is removed. +The preceding transformations are applied +repeatedly until none of them is applicable any more. +Any define element that is no longer reachable +is removed. + +
+ +
+<literal>empty</literal> element + +In this rule, the grammar is transformed so that an +empty element does not occur as a child of a +group, interleave, or +oneOrMore element or as the second child of +a choice element. A group, +interleave or choice element +that has two empty child elements is transformed +into an empty element. A group +or interleave element that has one +empty child element is transformed into its other +child element. A choice element whose +second child element is an empty element is +transformed by interchanging its two child elements. A +oneOrMore element that has an +empty child element is transformed into an +empty element. The preceding transformations are applied +repeatedly until none of them is applicable any more. + +
+ +
+ +
+Simple syntax + +After applying all the rules in , the schema will match the following +grammar: + + + +With this grammar, no elements or attributes are allowed other +than those explicitly shown. + +
+Example + +The following is an example of how the schema in can be transformed into the simple +syntax: + + + + + + + + + + foo + + + + + + + + + + bar1 + + + + + + + bar2 + + + +]]> + +Strictly speaking, the result of simplification is an +instance of the data model rather than an XML document. For +convenience, we use an XML document to represent an instance of the +data model. + +
+ +
+ +
+Semantics + +In this section, we define the semantics of a correct RELAX NG +schema that has been transformed into the simple syntax. The +semantics of a RELAX NG schema consist of a specification of what XML +documents are valid with respect to that schema. The semantics are +described formally. The formalism uses axioms and inference rules. +Axioms are propositions that are provable unconditionally. An +inference rule consists of one or more antecedents and exactly one +consequent. An antecedent is either positive or negative. If all the +positive antecedents of an inference rule are provable and none of the +negative antecedents are provable, then the consequent of the +inference rule is provable. An XML document is valid with respect to a +RELAX NG schema if and only if the proposition that it is valid is +provable in the formalism specified in this section. + +This kind of formalism is similar to a proof system. +However, a traditional proof system only has positive +antecedents. + +The notation for inference rules separates the antecedents from +the consequent by a horizontal line: the antecedents are above the +line; the consequent is below the line. If an antecedent is of the +form not(p), then it is a negative +antecedent; otherwise, it is a positive antecedent. Both axioms and +inferences +rules may use variables. A variable has a name and optionally a +subscript. The name of a variable is italicized. Each variable has a +range that is determined by its name. Axioms and inference rules are +implicitly universally quantified over the variables they contain. We +explain this further below. + +The possibility that an inference rule or axiom may contain more +than one occurrence of a particular variable requires that an identity +relation be defined on each kind of object over which a variable can +range. The identity relation for all kinds of object is value-based. +Two objects of a particular kind are identical if the constituents of +the objects are identical. For example, two attributes are considered +the same if they have the same name and the same value. Two characters +are identical if their Unicode character codes are the same. + +
+Name classes + +The main semantic concept for name classes is that of a name +belonging to a name class. A name class is an element that matches the +production nameClass. A name is as defined in : it consists of a namespace URI and a local +name. + +We use the following notation: + + + +is a variable +that ranges over names + +ranges over name classes + + + + + + +asserts that name is a member of name class + + + + + +We are now ready for our first axiom, which is called "anyName +1": + + + + + + + + + + +This says for any name , belongs to the name class , +in other words matches any name. Note the +effect of the implicit universal quantification over the variables in +the axiom: this is what makes the axiom apply for any name . + +Our first inference rule is almost as simple: + + + + + + + + + + + + + + + + + + + + + +This says that for any name +and for any name class , +if does not belong to , +then belongs to + + + + + . In other words, + + + + matches any name that does not match . + +We now need the following additional notation: + + + + + +ranges over local names; a local name is a string that +matches the NCName production of , that is, +a name with no colons + + +ranges over URIs + + + + + + + + +constructs a name with URI and local +name + + + + +The remaining axioms and inference rules for name classes are as +follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+Patterns + +The axioms and inference rules for patterns use the following +notation: + + + +ranges +over contexts (as defined in ) + +ranges over +sets of attributes; a set with a single member +is considered the same as that member + +ranges over sequences of +elements and strings; a sequence with a single member is considered +the same as that member; the sequences ranged over by may contain consecutive strings and may contain strings +that are empty; thus, there are sequences ranged over by that cannot occur as the children of an +element + +ranges +over patterns (elements matching the pattern +production) + + + + + + + + +asserts that with respect to context , the +attributes and the sequence of elements and +strings matches the pattern + + + +
+<literal>choice</literal> pattern + +The semantics of the choice pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+<literal>group</literal> pattern + +We use the following additional notation: + + + + + + + +represents the concatenation of the sequences and + + + + + + + +represents the union of +and + + + + + +The semantics of the group pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The restriction in +ensures that the set of attributes constructed in the consequent will +not have multiple attributes with the same name. + +
+ + +
+<literal>empty</literal> pattern + +We use the following additional notation: + + +represents an empty sequence + +represents an empty set + + + +The semantics of the empty pattern are as follows: + + + + + + + + + + + + + + +
+ + +
+<literal>text</literal> pattern + +We use the following additional notation: + + +ranges +over strings + + +The semantics of the text pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The effect of the above rule is that a text +element matches zero or more strings. + +
+ + +
+<literal>oneOrMore</literal> pattern + +We use the following additional notation: + + + + + + +asserts that there is no name that is +the name of both an attribute in +and of an attribute in + + + +The semantics of the oneOrMore pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+<literal>interleave</literal> pattern + +We use the following additional notation: + + + + + + + + +asserts that +is an interleaving of +and + + + + +The semantics of interleaving are defined by the following rules. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +For example, the interleavings of +]]> and +]]> are +]]>, +]]>, and +]]>. + +The semantics of the interleave pattern are +as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The restriction in +ensures that the set of attributes constructed in the consequent will +not have multiple attributes with the same name. + +
+ +
+<literal>element</literal> and <literal>attribute</literal> pattern + +The value of an attribute is always a single string, which may +be empty. Thus, the empty sequence is not a possible attribute value. +On the hand, the children of an element can be an empty sequence and +cannot consist of an empty string. In order to ensure that validation +handles attributes and elements consistently, we introduce a variant +of matching called weak matching. Weak +matching is used when matching the pattern for the value of an +attribute or for the attributes and children of an element. We use +the following notation to define weak matching. + + + +represents an empty +string + +ranges over the empty +sequence and strings that consist entirely of +whitespace + + + + + + + + +asserts that with respect to context , the +attributes and the sequence of elements and +strings weakly matches the pattern + + + +The semantics of weak matching are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +We use the following additional notation: + + + + + + + + +constructs an attribute with name +and value + + + + + + + + + +constructs an element with name , +context , +attributes +and mixed sequence as children + + + + + + +asserts that the mixed sequence can occur as +the children of an element: it does not contain any member that is an +empty string, nor does it contain two consecutive members that are +both strings + + + + + + + +asserts that the grammar contains + + + + + + + + + + + + + +The semantics of the attribute pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The semantics of the element pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+<literal>data</literal> and <literal>value</literal> pattern + +RELAX NG relies on datatype libraries to perform datatyping. +A datatype library is identified by a URI. A datatype within a +datatype library is identified by an NCName. A datatype library +provides two services. + + + +It can determine whether a string is a legal +representation of a datatype. This service accepts a list of zero or +more parameters. For example, a string datatype might have a parameter +specifying the length of a string. The datatype library determines +what parameters are applicable for each datatype. + +It can determine whether two strings represent the +same value of a datatype. This service does not have any +parameters. + + + +Both services may make use of the context of a string. For +example, a datatype representing a QName would use the namespace +map. + +We use the following additional notation: + + + + + + + + + + +asserts that in the datatype library identified by URI , the string interpreted with +context is a legal +value of datatype with parameters + + + + + + + + + + +asserts that in the datatype library identified by URI , string interpreted with +context represents the same value of +the datatype as the string interpreted in the context of + + +ranges over sequences of parameters + + + + + +within the start-tag of a pattern refers to the context +of the pattern element + + + + + + + + + +constructs a context which is the same as +except that the default namespace is ; if is the empty string, then there is no default namespace +in the constructed context + + + +The datatypeEqual function must be reflexive, transitive +and symmetric, that is, the following inference rules must hold: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The semantics of the data and +value patterns are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+Built-in datatype library + +The empty URI identifies a special built-in datatype library. +This provides two datatypes, string and +token. No parameters are allowed for either of +these datatypes. + + + + + + + +asserts that +and are identical + + + + + + + +returns the string , +with leading and trailing whitespace characters removed, +and with each other maximal sequence of whitespace characters +replaced by a single space character + + + +The semantics of the two built-in datatypes are as +follows: + + + + + + + string + + + + + + + + + + string + + + + + + + + + + + token + + + + + + + + + + + + + + + + + + token + + + + + + + + + +
+ +
+<literal>list</literal> pattern + +We use the following additional notation: + + + + + + +returns a sequence of strings one for each whitespace delimited token +of ; each string in the returned sequence will +be non-empty and will not contain any +whitespace + + + +The semantics of the list pattern are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + +It is crucial in the above inference rule that the +sequence that is matched against a pattern can contain consecutive +strings. + +
+ +
+ +
+Validity + +Now we can define when an element is valid with respect to a +schema. We use the following additional notation: + + + +ranges over elements + + + + + +asserts that the element is valid with +respect to the grammar + + + + +asserts that the grammar contains + + + + +An element is valid if together with an empty set of attributes +it matches the start pattern of the grammar. + + + + + + + + + + + + + + + + + + + + +
+ +
+Example + +Let be + + + + + + + foo + + + + + + + + +where is + + + + + + + + +and is + + + + + http://www.example.com/n1 + bar1 + + + + + + + +and is + + + + + http://www.example.com/n2 + bar2 + + + + + + + +Assuming appropriate definitions of , and , this represents the document in . + +We now show how can be shown to +be valid with respect to the schema in . The schema is equivalent to the +following propositions: + + + + + foo + + + + + + + foo.element + + + foo + + + + + bar1 + + + + + bar2 + + + + + + + + + bar1.element + + + http://www.example.com/n1 + + bar1 + + + + + + + + bar2.element + + + http://www.example.com/n2 + + bar2 + + + + + + +Let name class be + + + + + http://www.example.com/n1 + + bar1 + + + +and let be + + + + + http://www.example.com/n2 + + bar2 + + + +Then, by the inference rule (name) in , we have + + + + + http://www.example.com/n1 + bar1 + + + + + +and + + + + + http://www.example.com/n2 + bar2 + + + + + + +By the inference rule (empty) in , +we have + + + + + + + + + + +and + + + + + + + + + + +Thus by the inference rule (element) in , we have + + + + + + + + + bar1 + + + + + +Note that we have chosen , since any context is allowed. + +Likewise, we have + + + + + + + + + bar2 + + + + + +By the inference rule (group) in , we have + + + + + + + + + + + + + bar1 + + + + + bar2 + + + + + + +By the inference rule (element) in , we have + + + + + + + + + foo + + + + + + + + foo + + + + + +Here is an arbitrary +context. + +Thus we can apply the inference rule (valid) in and obtain + + + + + + + +
+ +
+ +
+Restrictions + +The following constraints are all checked after the grammar has +been transformed to the simple form described in . The purpose of these restrictions is to +catch user errors and to facilitate implementation. + +
+Contextual restrictions + +In this section we describe restrictions on where elements are +allowed in the schema based on the names of the ancestor elements. We +use the concept of a prohibited path to +describe these restrictions. A path is a sequence of NCNames separated +by / or //. + + + +An element matches a path +x, where x is an +NCName, if and only if the local name of the element is +x + +An element matches a path +x/p, +where x is an NCName and +p is a path, if and only if the local name +of the element is x and the element has a +child that matches p + +An element matches a path +x//p, +where x is an NCName and +p is a path, if and only if the local name +of the element is x and the element has a +descendant that matches p + + + +For example, the element + + + + + +]]> + +matches the paths foo, +foo/bar, foo//bar, +foo//baz, foo/bar/baz, +foo/bar//baz and foo//bar/baz, +but not foo/baz or +foobar. + +A correct RELAX NG schema must be such that, after +transformation to the simple form, it does not contain any element +that matches a prohibited path. + +
+<literal>attribute</literal> pattern + +The following paths are prohibited: + + +attribute//ref +attribute//attribute + + +
+ +
+<literal>oneOrMore</literal> pattern + +The following paths are prohibited: + + +oneOrMore//group//attribute +oneOrMore//interleave//attribute + + +
+ +
+<literal>list</literal> pattern + +The following paths are prohibited: + + +list//list +list//ref +list//attribute +list//text +list//interleave + +
+ +
+<literal>except</literal> in <literal>data</literal> pattern + +The following paths are prohibited: + + +data/except//attribute +data/except//ref +data/except//text +data/except//list +data/except//group +data/except//interleave +data/except//oneOrMore +data/except//empty + + +This implies that an except element +with a data parent can contain only +data, value and +choice elements. + +
+ +
+<literal>start</literal> element + +The following paths are prohibited: + + +start//attribute +start//data +start//value +start//text +start//list +start//group +start//interleave +start//oneOrMore +start//empty + +
+ +
+ +
+String sequences + +RELAX NG does not allow a pattern such as: + + + + + + + + +]]> + +Nor does it allow a pattern such as: + + + + + + +]]> + +More generally, if the pattern for the content of an element or +attribute contains + + + +a pattern that can match a child +(that is, an element, data, +value, list or +text pattern), and + +a pattern that matches a single string (that is, a +data, value or +list pattern), + + + +then the two patterns must be alternatives to each other. + +This rule does not apply to patterns occurring within a +list pattern. + +To formalize this, we use the concept of a content-type. A +pattern that is allowable as the content of an element has one of +three content-types: empty, complex and simple. We use the following +notation. + + + + + +returns the empty content-type + + + + +returns the complex content-type + + + + +returns the simple content-type + + + +ranges over content-types + + + + + + + + +asserts that the content-types and +are groupable + + + + +The empty content-type is groupable with anything. In addition, +the complex content-type is groupable with the complex content-type. The +following rules formalize this. + + + + + + + + + + + + + + + + + + + + + + +Some patterns have a content-type. We use the following +additional notation. + + + + + + + + + +asserts that pattern has +content-type + + + + + + + + +returns the maximum of and where the +content-types in increasing order are , +, + + + + +The following rules define when a pattern has a content-type and, +if so, what it is. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The antecedent in the (data 2) rule above is in fact +redundant because of the prohibited paths in . + +Now we can describe the restriction. We use the following +notation. + + + + + + +asserts that the schema is incorrect + + + + +All patterns occurring as the content of an element pattern must +have a content-type. + + + + + + + + + + + + + + + + + + + + +
+ +
+Restrictions on attributes + +Duplicate attributes are not allowed. More precisely, for a +pattern <group> p1 +p2 </group> or +<interleave> p1 +p2 </interleave>, there must +not be a name that belongs to both the name class of an +attribute pattern occurring in +p1 and the name class of an +attribute pattern occurring in +p2. A pattern p1 +is defined to occur in a pattern +p2 if + + + +p1 is +p2, or + +p2 is a +choice, interleave, +group or oneOrMore element and +p1 occurs in one or more children of +p2. + + + +Attributes using infinite name classes must be repeated. More +precisely, an attribute element that has an +anyName or nsName descendant +element must have a oneOrMore ancestor +element. + +This restriction is necessary for closure under +negation. + +
+ +
+Restrictions on <literal>interleave</literal> + +For a pattern <interleave> +p1 p2 +</interleave>, + + + +there must not be a name that belongs to both the name +class of an element pattern referenced by a +ref pattern occurring in +p1 and the name class of an +element pattern referenced by a +ref pattern occurring in +p2, and + +a text pattern must not occur in +both p1 and +p2. + + + + defines when one +pattern is considered to occur in another pattern. + +
+ +
+ +
+Conformance + +A conforming RELAX NG validator must be able to determine for +any XML document whether it is a correct RELAX NG schema. A +conforming RELAX NG validator must be able to determine for any XML +document and for any correct RELAX NG schema whether the document is +valid with respect to the schema. + +However, the requirements in the preceding paragraph do not +apply if the schema uses a datatype library that the validator does +not support. A conforming RELAX NG validator is only required to +support the built-in datatype library described in . A validator that claims conformance to +RELAX NG should document which datatype libraries it supports. The +requirements in the preceding paragraph also do not apply if the +schema includes externalRef or +include elements and the validator is unable to +retrieve the resource identified by the URI or is unable to construct +an element from the retrieved resource. A validator that claims +conformance to RELAX NG should document its capabilities for handling +URI references. + +
+ + +RELAX NG schema for RELAX NG + + + + + + +Changes since version 0.9 + +The changes in this version relative to version 0.9 +are as follows: + + + +in the namespace URI, 0.9 has been +changed to 1.0 + +data/except//empty has been added +as a prohibited path (see ) + +start//empty has been added +as a prohibited path (see ) + + now specifies how a +list element with more than one child element is +transformed + + now specifies how a +notAllowed element occurring in an +except element is transformed + +although a relative URI is not allowed as the value of +the ns and datatypeLibrary +attributes, an empty string is allowed (see ) + +the removal of unreachable definitions in is now correctly specified + + now specifies that +define elements that are no longer reachable are +removed + + has been added; the +restrictions on the contents of except in name +classes that are now specified in the newly added section were +previously specified in a subsection of , which has been +removed + +the treatment of element and attribute values that +consist only of whitespace has been refined (see and ) + +attributes with infinite name classes are now required +to be repeated (see ) + +restrictions have been imposed on +interleave (see ); list//interleave +has been added as a prohibited path (see ) + +some of the prohibited paths in have been corrected to use +ref rather than +element + +an error in the inference rule (text 1) in has been corrected + +the value of the ns attribute is +now unconstrained (see ) + + + + + + +RELAX NG TC (Non-Normative) + +This specification was prepared and approved for publication by +the RELAX NG TC. The current members of the TC are: + + +Fabio Arciniegas +James Clark +Mike Fitzgerald +KAWAGUCHI Kohsuke +Josh Lubell +MURATA Makoto +Norman Walsh +David Webber + + + + +References + +Normative + +XML 1.0Tim Bray, +Jean Paoli, and +C. M. Sperberg-McQueen, Eve Maler, editors. +Extensible Markup +Language (XML) 1.0 Second Edition. +W3C (World Wide Web Consortium), 2000. + +XML NamespacesTim Bray, +Dave Hollander, +and Andrew Layman, editors. +Namespaces in +XML. +W3C (World Wide Web Consortium), 1999. + +XLinkSteve DeRose, Eve Maler +and David Orchard, editors. +XML Linking +Language (XLink) Version 1.0. +W3C (World Wide Web Consortium), 2001. + +XML InfosetJohn Cowan, Richard Tobin, +editors. +XML +Information Set. +W3C (World Wide Web Consortium), 2001. + +RFC 2396T. Berners-Lee, R. Fielding, L. Masinter. +RFC 2396: +Uniform Resource Identifiers (URI): Generic +Syntax. +IETF (Internet Engineering Task Force). 1998. + +RFC 2732R. Hinden, B. Carpenter, L. Masinter. +RFC 2732: Format for Literal IPv6 Addresses in URL's. +IETF (Internet Engineering Task Force), 1999. + +RFC 3023 M. Murata, +S. St.Laurent, D. Kohn. RFC 3023: XML Media +Types. IETF (Internet Engineering Task Force), +2001. + + + +Non-Normative + +W3C XML Schema DatatypesPaul V. Biron, Ashok Malhotra, editors. +XML Schema Part 2: Datatypes. +W3C (World Wide Web Consortium), 2001. + +TREXJames Clark. +TREX - Tree Regular Expressions for XML. +Thai Open Source Software Center, 2001. + +RELAXMURATA Makoto. +RELAX (Regular +Language description for XML). INSTAC +(Information Technology Research and Standardization Center), 2001. + +XML Schema FormalAllen Brown, +Matthew Fuchs, Jonathan Robie, Philip Wadler, editors. +XML Schema: Formal Description. +W3C (World Wide Web Consortium), 2001. + +TutorialJames Clark, +Makoto MURATA, editors. RELAX +NG Tutorial. OASIS, 2001. + + + + + +
diff --git a/test/relaxng/testsuite.xml b/test/relaxng/testsuite.xml index 0c1b41e7..0d5a9474 100644 --- a/test/relaxng/testsuite.xml +++ b/test/relaxng/testsuite.xml @@ -1531,4 +1531,93 @@ + +Test of Mixed + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + mixed + + + + + + + + mixed + + + + + + + is + + inter + + mixed + + + + + + + mixed + + . + + + + + + this + + is + + inter + + mixed + + . + + + + + diff --git a/test/relaxng/tutor8_1_2.xml b/test/relaxng/tutor8_1_2.xml new file mode 100644 index 00000000..c1f37673 --- /dev/null +++ b/test/relaxng/tutor8_1_2.xml @@ -0,0 +1,7 @@ + + + b + b@b + + + diff --git a/valid.c b/valid.c index 491e5d48..b3b52c9f 100644 --- a/valid.c +++ b/valid.c @@ -2287,6 +2287,8 @@ xmlAddID(xmlValidCtxtPtr ctxt, xmlDocPtr doc, const xmlChar *value, xmlFreeID(ret); return(NULL); } + if (attr != NULL) + attr->atype = XML_ATTRIBUTE_ID; return(ret); } diff --git a/xmlschemastypes.c b/xmlschemastypes.c index 254e88de..0e1c7ccd 100644 --- a/xmlschemastypes.c +++ b/xmlschemastypes.c @@ -1526,15 +1526,22 @@ xmlSchemaValPredefTypeNode(xmlSchemaTypePtr type, const xmlChar *value, if ((ret == 0) && (node != NULL) && (node->type == XML_ATTRIBUTE_NODE)) { xmlAttrPtr attr = (xmlAttrPtr) node; - xmlChar *strip; - strip = xmlSchemaStrip(value); - if (strip != NULL) { - xmlAddRef(NULL, node->doc, strip, attr); - xmlFree(strip); - } else - xmlAddRef(NULL, node->doc, value, attr); - attr->atype = XML_ATTRIBUTE_IDREF; + /* + * NOTE: the REFness might have already be declared in the DTD + */ + if ((attr->atype != XML_ATTRIBUTE_IDREF) && + (attr->atype != XML_ATTRIBUTE_IDREFS)) { + xmlChar *strip; + + strip = xmlSchemaStrip(value); + if (strip != NULL) { + xmlAddRef(NULL, node->doc, strip, attr); + xmlFree(strip); + } else + xmlAddRef(NULL, node->doc, value, attr); + attr->atype = XML_ATTRIBUTE_IDREF; + } } return(ret); } else if (type == xmlSchemaTypeIdrefsDef) { @@ -1559,19 +1566,24 @@ xmlSchemaValPredefTypeNode(xmlSchemaTypePtr type, const xmlChar *value, if ((ret == 0) && (node != NULL) && (node->type == XML_ATTRIBUTE_NODE)) { xmlAttrPtr attr = (xmlAttrPtr) node; - xmlIDPtr res; - xmlChar *strip; + /* + * NOTE: the IDness might have already be declared in the DTD + */ + if (attr->atype != XML_ATTRIBUTE_ID) { + xmlIDPtr res; + xmlChar *strip; - strip = xmlSchemaStrip(value); - if (strip != NULL) { - res = xmlAddID(NULL, node->doc, strip, attr); - xmlFree(strip); - } else - res = xmlAddID(NULL, node->doc, value, attr); - if (res == NULL) { - ret = 2; - } else { - attr->atype = XML_ATTRIBUTE_ID; + strip = xmlSchemaStrip(value); + if (strip != NULL) { + res = xmlAddID(NULL, node->doc, strip, attr); + xmlFree(strip); + } else + res = xmlAddID(NULL, node->doc, value, attr); + if (res == NULL) { + ret = 2; + } else { + attr->atype = XML_ATTRIBUTE_ID; + } } } return(ret);