From: Daniel Veillard Date: Mon, 25 Jun 2001 10:58:40 +0000 (+0000) Subject: Lots of cleanup work toward betted multiple document output handling: X-Git-Tag: v1.1.28~1276 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=599b6b9743c71b3822700ae1a464102a0a9fd515;p=platform%2Fupstream%2Flibxslt.git Lots of cleanup work toward betted multiple document output handling: * libxslt/transform.[ch] libxslt/xslt.c libxslt/xsltInternals.h: added a new interface xsltRunStylesheet() for a more flexible handling of the output and trying to adhere to xsl:document filename generation semantic if one knows the URL of the output, also add IObuf capacity and SAX for output but is currently not implemented. * libxslt/xsltproc.c: added a -o or --output filename argument to test xsltRunStylesheet() or provide a base when generating multiple outputs * tests/docbook/Makefile.am tests/docbook/result/xtchunk/html/*: updated tests to add DocBook xt:document based chunking * tests/multiple/Makefile.am: cleaned up the makefile a bit * tests/multiple/out/*.html: the new xt:document now generate the DOCTYPE if available as is the case for HTML Daniel --- diff --git a/ChangeLog b/ChangeLog index abef01f..40c2c44 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +Mon Jun 25 12:41:30 CEST 2001 Daniel Veillard + + * libxslt/transform.[ch] libxslt/xslt.c libxslt/xsltInternals.h: + added a new interface xsltRunStylesheet() for a more flexible + handling of the output and trying to adhere to xsl:document + filename generation semantic if one knows the URL of the output, + also add IObuf capacity and SAX for output but is currently not + implemented. + * libxslt/xsltproc.c: added a -o or --output filename argument + to test xsltRunStylesheet() or provide a base when generating + multiple outputs + * tests/docbook/Makefile.am tests/docbook/result/xtchunk/html/*: + updated tests to add DocBook xt:document based chunking + * tests/multiple/Makefile.am: cleaned up the makefile a bit + * tests/multiple/out/*.html: the new xt:document now generate + the DOCTYPE if available as is the case for HTML + Mon Jun 25 08:45:00 HKT 2001 William Brack * Removed some redundant code in xsltDefaultProcessOneNode diff --git a/libxslt/transform.c b/libxslt/transform.c index 81e10c8..78fbe44 100644 --- a/libxslt/transform.c +++ b/libxslt/transform.c @@ -1071,135 +1071,366 @@ skip_children: * * Process an XSLT-1.1 document element */ -void +void xsltDocumentElem(xsltTransformContextPtr ctxt, xmlNodePtr node, - xmlNodePtr inst, xsltStylePreCompPtr comp) { + xmlNodePtr inst, xsltStylePreCompPtr comp) +{ xsltStylesheetPtr style = NULL; int ret; - xmlChar *filename = NULL; - xmlDocPtr result = NULL; + xmlChar *filename = NULL, *prop, *elements; + xmlChar *element, *end; + xmlDocPtr res = NULL; xmlDocPtr oldOutput; xmlNodePtr oldInsert; + const char *oldOutputFile; + xsltOutputType oldType; + xmlChar *URL = NULL; + const xmlChar *method; + const xmlChar *doctypePublic; + const xmlChar *doctypeSystem; + const xmlChar *version; - if ((ctxt == NULL) || (node == NULL) || (inst == NULL) || (comp == NULL)) - return; + if ((ctxt == NULL) || (node == NULL) || (inst == NULL) + || (comp == NULL)) + return; if (comp->filename == NULL) { - xmlChar *base = NULL; - xmlChar *URL = NULL; - if (xmlStrEqual(inst->name, (const xmlChar *) "output")) { + + if (xmlStrEqual(inst->name, (const xmlChar *) "output")) { #ifdef WITH_XSLT_DEBUG_EXTRA - xsltGenericDebug(xsltGenericDebugContext, - "Found saxon:output extension\n"); + xsltGenericDebug(xsltGenericDebugContext, + "Found saxon:output extension\n"); #endif - filename = xsltEvalAttrValueTemplate(ctxt, inst, - (const xmlChar *)"file", - XSLT_SAXON_NAMESPACE); - } else if (xmlStrEqual(inst->name, (const xmlChar *) "write")) { + URL = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "file", + XSLT_SAXON_NAMESPACE); + } else if (xmlStrEqual(inst->name, (const xmlChar *) "write")) { #ifdef WITH_XSLT_DEBUG_EXTRA - xsltGenericDebug(xsltGenericDebugContext, - "Found xalan:write extension\n"); -#endif - filename = xsltEvalAttrValueTemplate(ctxt, inst, - (const xmlChar *)"select", - XSLT_XALAN_NAMESPACE); - } else if (xmlStrEqual(inst->name, (const xmlChar *) "document")) { - filename = xsltEvalAttrValueTemplate(ctxt, inst, - (const xmlChar *)"href", - XSLT_XT_NAMESPACE); - if (filename == NULL) { + xsltGenericDebug(xsltGenericDebugContext, + "Found xalan:write extension\n"); +#endif + URL = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "select", + XSLT_XALAN_NAMESPACE); + } else if (xmlStrEqual(inst->name, (const xmlChar *) "document")) { + URL = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "href", + XSLT_XT_NAMESPACE); + if (URL == NULL) { #ifdef WITH_XSLT_DEBUG_EXTRA - xsltGenericDebug(xsltGenericDebugContext, - "Found xslt11:document construct\n"); + xsltGenericDebug(xsltGenericDebugContext, + "Found xslt11:document construct\n"); #endif - filename = xsltEvalAttrValueTemplate(ctxt, inst, - (const xmlChar *)"href", - XSLT_NAMESPACE); - comp->ver11 = 1; - } else { + URL = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "href", + XSLT_NAMESPACE); + comp->ver11 = 1; + } else { #ifdef WITH_XSLT_DEBUG_EXTRA - xsltGenericDebug(xsltGenericDebugContext, - "Found xt:document extension\n"); + xsltGenericDebug(xsltGenericDebugContext, + "Found xt:document extension\n"); #endif - comp->ver11 = 0; - } - } - if (filename == NULL) - return; + comp->ver11 = 0; + } + } - /* - * Compute output URL - */ - base = xmlNodeGetBase(inst->doc, inst); - URL = xmlBuildURI(filename, base); - if (URL == NULL) { - xsltGenericError(xsltGenericErrorContext, - "xsltDocumentElem: URL computation failed %s\n", filename); - } else { - xmlFree(filename); - filename = URL; - } - if (base != NULL) - xmlFree(base); } else { - filename = xmlStrdup(comp->filename); + URL = xmlStrdup(comp->filename); + } + + if (URL == NULL) { + xsltGenericError(xsltGenericErrorContext, + "xsltDocumentElem: href/URI-Reference not found\n"); + return; + } + filename = xmlBuildURI(URL, (const xmlChar *) ctxt->outputFile); + if (filename == NULL) { + xsltGenericError(xsltGenericErrorContext, + "xsltDocumentElem: URL computation failed for %s\n", + URL); + xmlFree(URL); + return; } + oldOutputFile = ctxt->outputFile; oldOutput = ctxt->output; oldInsert = ctxt->insert; + oldType = ctxt->type; + ctxt->outputFile = (const char *) filename; style = xsltNewStylesheet(); if (style == NULL) { - xsltGenericError(xsltGenericErrorContext, - "xsltDocumentElem: out of memory\n"); - goto error; + xsltGenericError(xsltGenericErrorContext, + "xsltDocumentElem: out of memory\n"); + goto error; } /* * Version described in 1.1 draft allows full parametrization * of the output. */ - xsltParseStylesheetOutput(style, inst); + if (comp->ver11) { + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "version", + XSLT_NAMESPACE); + if (prop != NULL) { + if (style->version != NULL) + xmlFree(style->version); + style->version = prop; + } + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "encoding", + XSLT_NAMESPACE); + if (prop != NULL) { + if (style->encoding != NULL) + xmlFree(style->encoding); + style->encoding = prop; + } + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "method", + XSLT_NAMESPACE); + if (prop != NULL) { + xmlChar *ncname; + xmlChar *prefix = NULL; + + if (style->method != NULL) + xmlFree(style->method); + style->method = NULL; + if (style->methodURI != NULL) + xmlFree(style->methodURI); + style->methodURI = NULL; + + ncname = xmlSplitQName2(prop, &prefix); + if (ncname != NULL) { + if (prefix != NULL) { + xmlNsPtr ns; + + ns = xmlSearchNs(inst->doc, inst, prefix); + if (ns == NULL) { + xsltGenericError(xsltGenericErrorContext, + "no namespace bound to prefix %s\n", + prefix); + style->warnings++; + xmlFree(prefix); + xmlFree(ncname); + style->method = prop; + } else { + style->methodURI = xmlStrdup(ns->href); + style->method = ncname; + xmlFree(prefix); + xmlFree(prop); + } + } else { + style->method = ncname; + xmlFree(prop); + } + } else { + if ((xmlStrEqual(prop, (const xmlChar *) "xml")) || + (xmlStrEqual(prop, (const xmlChar *) "html")) || + (xmlStrEqual(prop, (const xmlChar *) "text"))) { + style->method = prop; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for method: %s\n", + prop); + style->warnings++; + } + } + } + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "doctype-system", XSLT_NAMESPACE); + if (prop != NULL) { + if (style->doctypeSystem != NULL) + xmlFree(style->doctypeSystem); + style->doctypeSystem = prop; + } + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "doctype-public", XSLT_NAMESPACE); + if (prop != NULL) { + if (style->doctypePublic != NULL) + xmlFree(style->doctypePublic); + style->doctypePublic = prop; + } + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "standalone", + XSLT_NAMESPACE); + if (prop != NULL) { + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->standalone = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->standalone = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for standalone: %s\n", + prop); + style->warnings++; + } + xmlFree(prop); + } + + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) "indent", + XSLT_NAMESPACE); + if (prop != NULL) { + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->indent = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->indent = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for indent: %s\n", prop); + style->warnings++; + } + xmlFree(prop); + } + + prop = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "omit-xml-declaration", + XSLT_NAMESPACE); + if (prop != NULL) { + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->omitXmlDeclaration = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->omitXmlDeclaration = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for omit-xml-declaration: %s\n", + prop); + style->warnings++; + } + xmlFree(prop); + } + + elements = xsltEvalAttrValueTemplate(ctxt, inst, + (const xmlChar *) + "cdata-section-elements", + XSLT_NAMESPACE); + if (elements != NULL) { + if (style->stripSpaces == NULL) + style->stripSpaces = xmlHashCreate(10); + if (style->stripSpaces == NULL) + return; + + element = elements; + while (*element != 0) { + while (IS_BLANK(*element)) + element++; + if (*element == 0) + break; + end = element; + while ((*end != 0) && (!IS_BLANK(*end))) + end++; + element = xmlStrndup(element, end - element); + if (element) { +#ifdef WITH_XSLT_DEBUG_PARSING + xsltGenericDebug(xsltGenericDebugContext, + "add cdata section output element %s\n", + element); +#endif + xmlHashAddEntry(style->stripSpaces, element, + (xmlChar *) "cdata"); + xmlFree(element); + } + element = end; + } + xmlFree(elements); + } + } else { + xsltParseStylesheetOutput(style, inst); + } /* * Create a new document tree and process the element template */ - result = xmlNewDoc(style->version); - if (result == NULL) { - xsltGenericError(xsltGenericErrorContext, - "xsltDocumentElem: out of memory\n"); - goto error; + XSLT_GET_IMPORT_PTR(method, style, method) + XSLT_GET_IMPORT_PTR(doctypePublic, style, doctypePublic) + XSLT_GET_IMPORT_PTR(doctypeSystem, style, doctypeSystem) + XSLT_GET_IMPORT_PTR(version, style, version) + + if ((method != NULL) && + (!xmlStrEqual(method, (const xmlChar *) "xml"))) { + if (xmlStrEqual(method, (const xmlChar *) "html")) { + ctxt->type = XSLT_OUTPUT_HTML; + if (((doctypePublic != NULL) || (doctypeSystem != NULL))) + res = htmlNewDoc(doctypeSystem, doctypePublic); + else { + if (version == NULL) + version = (const xmlChar *) "4.0"; +#ifdef XSLT_GENERATE_HTML_DOCTYPE + xsltGetHTMLIDs(version, &doctypePublic, &doctypeSystem); +#endif + res = htmlNewDoc(doctypeSystem, doctypePublic); + } + if (res == NULL) + goto error; + } else if (xmlStrEqual(method, (const xmlChar *) "xhtml")) { + xsltGenericError(xsltGenericErrorContext, + "xsltApplyStylesheet: unsupported method xhtml, using html\n", + style->method); + ctxt->type = XSLT_OUTPUT_HTML; + res = htmlNewDoc(doctypeSystem, doctypePublic); + if (res == NULL) + goto error; + } else if (xmlStrEqual(style->method, (const xmlChar *) "text")) { + ctxt->type = XSLT_OUTPUT_TEXT; + res = xmlNewDoc(style->version); + if (res == NULL) + goto error; + } else { + xsltGenericError(xsltGenericErrorContext, + "xsltApplyStylesheet: unsupported method %s\n", + style->method); + goto error; + } + } else { + ctxt->type = XSLT_OUTPUT_XML; + res = xmlNewDoc(style->version); + if (res == NULL) + goto error; } - ctxt->output = result; - ctxt->insert = (xmlNodePtr) result; + res->charset = XML_CHAR_ENCODING_UTF8; + if (style->encoding != NULL) + res->encoding = xmlStrdup(style->encoding); + ctxt->output = res; + ctxt->insert = (xmlNodePtr) res; varsPush(ctxt, NULL); xsltApplyOneTemplate(ctxt, node, inst->children, 0); xsltFreeStackElemList(varsPop(ctxt)); /* - * Save the result + * Save the res */ ret = xsltSaveResultToFilename((const char *) filename, - result, style, 0); + res, style, 0); if (ret < 0) { - xsltGenericError(xsltGenericErrorContext, - "xsltDocumentElem: unable to save to %s\n", filename); + xsltGenericError(xsltGenericErrorContext, + "xsltDocumentElem: unable to save to %s\n", + filename); #ifdef WITH_XSLT_DEBUG_EXTRA } else { - xsltGenericDebug(xsltGenericDebugContext, - "Wrote %d bytes to %s\n", ret, , filename); + xsltGenericDebug(xsltGenericDebugContext, + "Wrote %d bytes to %s\n", ret,, filename); #endif } -error: + error: ctxt->output = oldOutput; ctxt->insert = oldInsert; + ctxt->type = oldType; + ctxt->outputFile = oldOutputFile; + if (URL != NULL) + xmlFree(URL); if (filename != NULL) xmlFree(filename); if (style != NULL) - xsltFreeStylesheet(style); - if (result != NULL) - xmlFreeDoc(result); + xsltFreeStylesheet(style); + if (res != NULL) + xmlFreeDoc(res); } /************************************************************************ @@ -2028,7 +2259,6 @@ xsltApplyTemplates(xsltTransformContextPtr ctxt, xmlNodePtr node, const xmlChar *oldMode, *oldModeURI; xsltStackElemPtr params = NULL, param, tmp, p; int nbsorts = 0; - int newdoc = 0; xmlNodePtr sorts[XSLT_MAX_SORT]; xmlDocPtr oldXDocPtr; xsltDocumentPtr oldCDocPtr; @@ -2452,8 +2682,8 @@ xsltForEach(xsltTransformContextPtr ctxt, xmlNodePtr node, xmlNodePtr oldNode = ctxt->node; int nbsorts = 0; xmlNodePtr sorts[XSLT_MAX_SORT]; - xmlDocPtr oldXDocPtr, newXDocPtr; - xsltDocumentPtr oldCDocPtr, newCDocPtr; + xmlDocPtr oldXDocPtr; + xsltDocumentPtr oldCDocPtr; if ((ctxt == NULL) || (node == NULL) || (inst == NULL)) return; @@ -2623,19 +2853,20 @@ xsltGetHTMLIDs(const xmlChar *version, const xmlChar **public, #endif /** - * xsltApplyStylesheet: + * xsltApplyStylesheetInternal: * @style: a parsed XSLT stylesheet * @doc: a parsed XML document * @params: a NULL terminated arry of parameters names/values tuples + * @output: the targetted output * * Apply the stylesheet to the document * NOTE: This may lead to a non-wellformed output XML wise ! * * Returns the result document or NULL in case of error */ -xmlDocPtr -xsltApplyStylesheet(xsltStylesheetPtr style, xmlDocPtr doc, - const char **params) { +static xmlDocPtr +xsltApplyStylesheetInternal(xsltStylesheetPtr style, xmlDocPtr doc, + const char **params, const char *output) { xmlDocPtr res = NULL; xsltTransformContextPtr ctxt = NULL; xmlNodePtr root; @@ -2650,9 +2881,13 @@ xsltApplyStylesheet(xsltStylesheetPtr style, xmlDocPtr doc, if ((style == NULL) || (doc == NULL)) return(NULL); ctxt = xsltNewTransformContext(style, doc); - xsltRegisterExtras(ctxt); if (ctxt == NULL) return(NULL); + xsltRegisterExtras(ctxt); + if (output != NULL) + ctxt->outputFile = output; + else + ctxt->outputFile = NULL; XSLT_GET_IMPORT_PTR(method, style, method) XSLT_GET_IMPORT_PTR(doctypePublic, style, doctypePublic) @@ -2807,3 +3042,78 @@ error: return(NULL); } +/** + * xsltApplyStylesheet: + * @style: a parsed XSLT stylesheet + * @doc: a parsed XML document + * @params: a NULL terminated arry of parameters names/values tuples + * + * Apply the stylesheet to the document + * NOTE: This may lead to a non-wellformed output XML wise ! + * + * Returns the result document or NULL in case of error + */ +xmlDocPtr +xsltApplyStylesheet(xsltStylesheetPtr style, xmlDocPtr doc, + const char **params) { + return(xsltApplyStylesheetInternal(style, doc, params, NULL)); +} + +/** + * xsltRunStylesheet: + * @style: a parsed XSLT stylesheet + * @doc: a parsed XML document + * @params: a NULL terminated arry of parameters names/values tuples + * @output: the URL/filename ot the generated resource if available + * @SAX: a SAX handler for progressive callback output (not implemented yet) + * @IObuf: an output buffer for progressive output (not implemented yet) + * + * Apply the stylesheet to the document and generate the output according + * to @output @SAX and @IObuf. It's an error to specify both @SAX and @IObuf. + * + * NOTE: This may lead to a non-wellformed output XML wise ! + * NOTE: This may also result in multiple files being generated + * NOTE: using IObuf, the result encoding used will be the one used for + * creating the output buffer, use the following macro to read it + * from the stylesheet + * XSLT_GET_IMPORT_PTR(encoding, style, encoding) + * NOTE: using SAX, any encoding specified in the stylesheet will be lost + * since the interface uses only UTF8 + * + * Returns the number of by written to the main resource or -1 in case of + * error. + */ +int +xsltRunStylesheet(xsltStylesheetPtr style, xmlDocPtr doc, const char **params, + const char *output, xmlSAXHandlerPtr SAX, + xmlOutputBufferPtr IObuf) +{ + xmlDocPtr tmp; + int ret; + + if ((output == NULL) && (SAX == NULL) && (IObuf == NULL)) + return(-1); + if ((SAX != NULL) && (IObuf != NULL)) + return(-1); + + /* unsupported yet */ + if (SAX != NULL) { + TODO /* xsltRunStylesheet xmlSAXHandlerPtr SAX */ + return(-1); + } + + tmp = xsltApplyStylesheetInternal(style, doc, params, output); + if (tmp == NULL) { + xsltGenericError(xsltGenericErrorContext, + "xsltRunStylesheet : run failed\n"); + return(-1); + } + if (IObuf != NULL) { + /* TODO: incomplete, IObuf output not progressive */ + ret = xsltSaveResultTo(IObuf, tmp, style); + } else { + ret = xsltSaveResultToFilename(output, tmp, style, 0); + } + xmlFreeDoc(tmp); + return(ret); +} diff --git a/libxslt/transform.h b/libxslt/transform.h index 46ed133..ff9a085 100644 --- a/libxslt/transform.h +++ b/libxslt/transform.h @@ -10,7 +10,8 @@ #ifndef __XML_XSLT_TRANSFORM_H__ #define __XML_XSLT_TRANSFORM_H__ -#include +#include +#include #ifdef __cplusplus extern "C" { @@ -28,6 +29,12 @@ int xsltGetXIncludeDefault (void); xmlDocPtr xsltApplyStylesheet (xsltStylesheetPtr style, xmlDocPtr doc, const char **params); +int xsltRunStylesheet (xsltStylesheetPtr style, + xmlDocPtr doc, + const char **params, + const char *output, + xmlSAXHandlerPtr SAX, + xmlOutputBufferPtr IObuf); void xsltApplyOneTemplate (xsltTransformContextPtr ctxt, xmlNodePtr node, xmlNodePtr list, diff --git a/libxslt/xslt.c b/libxslt/xslt.c index 69b2e5d..c576a53 100644 --- a/libxslt/xslt.c +++ b/libxslt/xslt.c @@ -298,9 +298,10 @@ xsltFreeStylesheetList(xsltStylesheetPtr sheet) { * Free up the memory allocated by @sheet */ void -xsltFreeStylesheet(xsltStylesheetPtr sheet) { +xsltFreeStylesheet(xsltStylesheetPtr sheet) +{ if (sheet == NULL) - return; + return; xsltFreeKeys(sheet); xsltFreeExts(sheet); @@ -312,24 +313,31 @@ xsltFreeStylesheet(xsltStylesheetPtr sheet) { xsltFreeStyleDocuments(sheet); xsltFreeStylePreComps(sheet); if (sheet->doc != NULL) - xmlFreeDoc(sheet->doc); + xmlFreeDoc(sheet->doc); if (sheet->variables != NULL) - xsltFreeStackElemList(sheet->variables); + xsltFreeStackElemList(sheet->variables); if (sheet->stripSpaces != NULL) - xmlHashFree(sheet->stripSpaces, NULL); - if (sheet->nsHash != NULL) - xmlHashFree(sheet->nsHash, NULL); - - if (sheet->method != NULL) xmlFree(sheet->method); - if (sheet->methodURI != NULL) xmlFree(sheet->methodURI); - if (sheet->version != NULL) xmlFree(sheet->version); - if (sheet->encoding != NULL) xmlFree(sheet->encoding); - if (sheet->doctypePublic != NULL) xmlFree(sheet->doctypePublic); - if (sheet->doctypeSystem != NULL) xmlFree(sheet->doctypeSystem); - if (sheet->mediaType != NULL) xmlFree(sheet->mediaType); + xmlHashFree(sheet->stripSpaces, NULL); + if (sheet->nsHash != NULL) + xmlHashFree(sheet->nsHash, NULL); + + if (sheet->method != NULL) + xmlFree(sheet->method); + if (sheet->methodURI != NULL) + xmlFree(sheet->methodURI); + if (sheet->version != NULL) + xmlFree(sheet->version); + if (sheet->encoding != NULL) + xmlFree(sheet->encoding); + if (sheet->doctypePublic != NULL) + xmlFree(sheet->doctypePublic); + if (sheet->doctypeSystem != NULL) + xmlFree(sheet->doctypeSystem); + if (sheet->mediaType != NULL) + xmlFree(sheet->mediaType); if (sheet->imports != NULL) - xsltFreeStylesheetList(sheet->imports); + xsltFreeStylesheetList(sheet->imports); memset(sheet, -1, sizeof(xsltStylesheet)); xmlFree(sheet); @@ -351,157 +359,176 @@ xsltFreeStylesheet(xsltStylesheetPtr sheet) { */ void -xsltParseStylesheetOutput(xsltStylesheetPtr style, xmlNodePtr cur) { - xmlChar *elements, *prop; - xmlChar *element, *end; +xsltParseStylesheetOutput(xsltStylesheetPtr style, xmlNodePtr cur) +{ + xmlChar *elements, + *prop; + xmlChar *element, + *end; if ((cur == NULL) || (style == NULL)) - return; + return; - prop = xsltGetNsProp(cur, (const xmlChar *)"version", XSLT_NAMESPACE); + prop = xsltGetNsProp(cur, (const xmlChar *) "version", XSLT_NAMESPACE); if (prop != NULL) { - if (style->version != NULL) xmlFree(style->version); - style->version = prop; + if (style->version != NULL) + xmlFree(style->version); + style->version = prop; } - prop = xsltGetNsProp(cur, (const xmlChar *)"encoding", XSLT_NAMESPACE); + prop = + xsltGetNsProp(cur, (const xmlChar *) "encoding", XSLT_NAMESPACE); if (prop != NULL) { - if (style->encoding != NULL) xmlFree(style->encoding); - style->encoding = prop; + if (style->encoding != NULL) + xmlFree(style->encoding); + style->encoding = prop; } /* relaxed to support xt:document */ - prop = xmlGetProp(cur, (const xmlChar *)"method"); + prop = xmlGetProp(cur, (const xmlChar *) "method"); if (prop != NULL) { - xmlChar *ncname; - xmlChar *prefix = NULL; - - if (style->method != NULL) xmlFree(style->method); - style->method = NULL; - if (style->methodURI != NULL) xmlFree(style->methodURI); - style->methodURI = NULL; - - ncname = xmlSplitQName2(prop, &prefix); - if (ncname != NULL) { - if (prefix != NULL) { - xmlNsPtr ns; - - ns = xmlSearchNs(cur->doc, cur, prefix); - if (ns == NULL) { - xsltGenericError(xsltGenericErrorContext, - "no namespace bound to prefix %s\n", prefix); - style->warnings++; - xmlFree(prefix); - xmlFree(ncname); - style->method = prop; - } else { - style->methodURI = xmlStrdup(ns->href); - style->method = ncname; - xmlFree(prefix); - xmlFree(prop); - } - } else { - style->method = ncname; - xmlFree(prop); - } - } else { - if ((xmlStrEqual(prop, (const xmlChar *)"xml")) || - (xmlStrEqual(prop, (const xmlChar *)"html")) || - (xmlStrEqual(prop, (const xmlChar *)"text"))) { - style->method = prop; - } else { - xsltGenericError(xsltGenericErrorContext, - "invalid value for method: %s\n", prop); - style->warnings++; - } - } + xmlChar *ncname; + xmlChar *prefix = NULL; + + if (style->method != NULL) + xmlFree(style->method); + style->method = NULL; + if (style->methodURI != NULL) + xmlFree(style->methodURI); + style->methodURI = NULL; + + ncname = xmlSplitQName2(prop, &prefix); + if (ncname != NULL) { + if (prefix != NULL) { + xmlNsPtr ns; + + ns = xmlSearchNs(cur->doc, cur, prefix); + if (ns == NULL) { + xsltGenericError(xsltGenericErrorContext, + "no namespace bound to prefix %s\n", + prefix); + style->warnings++; + xmlFree(prefix); + xmlFree(ncname); + style->method = prop; + } else { + style->methodURI = xmlStrdup(ns->href); + style->method = ncname; + xmlFree(prefix); + xmlFree(prop); + } + } else { + style->method = ncname; + xmlFree(prop); + } + } else { + if ((xmlStrEqual(prop, (const xmlChar *) "xml")) || + (xmlStrEqual(prop, (const xmlChar *) "html")) || + (xmlStrEqual(prop, (const xmlChar *) "text"))) { + style->method = prop; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for method: %s\n", prop); + style->warnings++; + } + } } - prop = xsltGetNsProp(cur, (const xmlChar *)"doctype-system", XSLT_NAMESPACE); + prop = + xsltGetNsProp(cur, (const xmlChar *) "doctype-system", + XSLT_NAMESPACE); if (prop != NULL) { - if (style->doctypeSystem != NULL) xmlFree(style->doctypeSystem); - style->doctypeSystem = prop; + if (style->doctypeSystem != NULL) + xmlFree(style->doctypeSystem); + style->doctypeSystem = prop; } - prop = xsltGetNsProp(cur, (const xmlChar *)"doctype-public", XSLT_NAMESPACE); + prop = + xsltGetNsProp(cur, (const xmlChar *) "doctype-public", + XSLT_NAMESPACE); if (prop != NULL) { - if (style->doctypePublic != NULL) xmlFree(style->doctypePublic); - style->doctypePublic = prop; + if (style->doctypePublic != NULL) + xmlFree(style->doctypePublic); + style->doctypePublic = prop; } - prop = xsltGetNsProp(cur, (const xmlChar *)"standalone", - XSLT_NAMESPACE); + prop = xsltGetNsProp(cur, (const xmlChar *) "standalone", + XSLT_NAMESPACE); if (prop != NULL) { - if (xmlStrEqual(prop, (const xmlChar *)"yes")) { - style->standalone = 1; - } else if (xmlStrEqual(prop, (const xmlChar *)"no")) { - style->standalone = 0; - } else { - xsltGenericError(xsltGenericErrorContext, - "invalid value for standalone: %s\n", prop); - style->warnings++; - } - xmlFree(prop); + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->standalone = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->standalone = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for standalone: %s\n", prop); + style->warnings++; + } + xmlFree(prop); } - prop = xsltGetNsProp(cur, (const xmlChar *)"indent", - XSLT_NAMESPACE); + prop = xsltGetNsProp(cur, (const xmlChar *) "indent", XSLT_NAMESPACE); if (prop != NULL) { - if (xmlStrEqual(prop, (const xmlChar *)"yes")) { - style->indent = 1; - } else if (xmlStrEqual(prop, (const xmlChar *)"no")) { - style->indent = 0; - } else { - xsltGenericError(xsltGenericErrorContext, - "invalid value for indent: %s\n", prop); - style->warnings++; - } - xmlFree(prop); + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->indent = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->indent = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for indent: %s\n", prop); + style->warnings++; + } + xmlFree(prop); } - prop = xsltGetNsProp(cur, (const xmlChar *)"omit-xml-declaration", - XSLT_NAMESPACE); + prop = xsltGetNsProp(cur, (const xmlChar *) "omit-xml-declaration", + XSLT_NAMESPACE); if (prop != NULL) { - if (xmlStrEqual(prop, (const xmlChar *)"yes")) { - style->omitXmlDeclaration = 1; - } else if (xmlStrEqual(prop, (const xmlChar *)"no")) { - style->omitXmlDeclaration = 0; - } else { - xsltGenericError(xsltGenericErrorContext, - "invalid value for omit-xml-declaration: %s\n", prop); - style->warnings++; - } - xmlFree(prop); + if (xmlStrEqual(prop, (const xmlChar *) "yes")) { + style->omitXmlDeclaration = 1; + } else if (xmlStrEqual(prop, (const xmlChar *) "no")) { + style->omitXmlDeclaration = 0; + } else { + xsltGenericError(xsltGenericErrorContext, + "invalid value for omit-xml-declaration: %s\n", + prop); + style->warnings++; + } + xmlFree(prop); } - elements = xsltGetNsProp(cur, (const xmlChar *)"cdata-section-elements", - XSLT_NAMESPACE); + elements = + xsltGetNsProp(cur, (const xmlChar *) "cdata-section-elements", + XSLT_NAMESPACE); if (elements != NULL) { - if (style->stripSpaces == NULL) - style->stripSpaces = xmlHashCreate(10); - if (style->stripSpaces == NULL) - return; - - element = elements; - while (*element != 0) { - while (IS_BLANK(*element)) element++; - if (*element == 0) - break; - end = element; - while ((*end != 0) && (!IS_BLANK(*end))) end++; - element = xmlStrndup(element, end - element); - if (element) { + if (style->stripSpaces == NULL) + style->stripSpaces = xmlHashCreate(10); + if (style->stripSpaces == NULL) + return; + + element = elements; + while (*element != 0) { + while (IS_BLANK(*element)) + element++; + if (*element == 0) + break; + end = element; + while ((*end != 0) && (!IS_BLANK(*end))) + end++; + element = xmlStrndup(element, end - element); + if (element) { #ifdef WITH_XSLT_DEBUG_PARSING - xsltGenericDebug(xsltGenericDebugContext, - "add cdata section output element %s\n", element); + xsltGenericDebug(xsltGenericDebugContext, + "add cdata section output element %s\n", + element); #endif - xmlHashAddEntry(style->stripSpaces, element, - (xmlChar *) "cdata"); - xmlFree(element); - } - element = end; - } - xmlFree(elements); + xmlHashAddEntry(style->stripSpaces, element, + (xmlChar *) "cdata"); + xmlFree(element); + } + element = end; + } + xmlFree(elements); } } diff --git a/libxslt/xsltInternals.h b/libxslt/xsltInternals.h index 58ef1c2..8999465 100644 --- a/libxslt/xsltInternals.h +++ b/libxslt/xsltInternals.h @@ -366,6 +366,8 @@ struct _xsltTransformContext { xmlNodePtr inst; /* the instruction in the stylesheet */ int xinclude; /* should XInclude be processed */ + + const char * outputFile; /* the output URI if known */ }; /** diff --git a/libxslt/xsltproc.c b/libxslt/xsltproc.c index 1af2437..43745b7 100644 --- a/libxslt/xsltproc.c +++ b/libxslt/xsltproc.c @@ -91,6 +91,7 @@ static void usage(const char *name) { printf(" Options:\n"); printf(" --version or -V: show the version of libxml and libxslt used\n"); printf(" --verbose or -v: show logs of what's happening\n"); + printf(" --output file or -v file: save to a given file\n"); printf(" --timing: display the time used\n"); printf(" --repeat: run the transformation 20 times\n"); printf(" --debug: dump the tree of the result instead\n"); @@ -115,297 +116,335 @@ static void usage(const char *name) { } int -main(int argc, char **argv) { +main(int argc, char **argv) +{ int i; xsltStylesheetPtr cur = NULL; xmlDocPtr doc, res; struct timeval begin, end; const char *params[16 + 1]; int nbparams = 0; + const char *output = NULL; if (argc <= 1) { - usage(argv[0]); - return(1); + usage(argv[0]); + return (1); } xmlInitMemory(); - LIBXML_TEST_VERSION - defaultLoader = xmlGetExternalEntityLoader(); - for (i = 1; i < argc ; i++) { - if (!strcmp(argv[i], "-")) - break; + LIBXML_TEST_VERSION defaultLoader = xmlGetExternalEntityLoader(); + for (i = 1; i < argc; i++) { + if (!strcmp(argv[i], "-")) + break; - if (argv[i][0] != '-') - continue; + if (argv[i][0] != '-') + continue; #ifdef LIBXML_DEBUG_ENABLED - if ((!strcmp(argv[i], "-debug")) || (!strcmp(argv[i], "--debug"))) { - debug++; - } else + if ((!strcmp(argv[i], "-debug")) || (!strcmp(argv[i], "--debug"))) { + debug++; + } else #endif - if ((!strcmp(argv[i], "-v")) || - (!strcmp(argv[i], "-verbose")) || - (!strcmp(argv[i], "--verbose"))) { - xsltSetGenericDebugFunc(stderr, NULL); - } else if ((!strcmp(argv[i], "-V")) || - (!strcmp(argv[i], "-version")) || - (!strcmp(argv[i], "--version"))) { - printf("Using libxml %s and libxslt %s\n", - xmlParserVersion, xsltEngineVersion); - printf("xsltproc was compiled against libxml %d and libxslt %d\n", - LIBXML_VERSION, LIBXSLT_VERSION); - printf("libxslt %d was compiled against libxml %d\n", - xsltLibxsltVersion, xsltLibxmlVersion); - } else if ((!strcmp(argv[i], "-repeat")) || - (!strcmp(argv[i], "--repeat"))) { - if (repeat == 0) - repeat = 20; - else - repeat = 100; - } else if ((!strcmp(argv[i], "-novalid")) || - (!strcmp(argv[i], "--novalid"))) { - novalid++; - } else if ((!strcmp(argv[i], "-noout")) || - (!strcmp(argv[i], "--noout"))) { - noout++; + if ((!strcmp(argv[i], "-v")) || + (!strcmp(argv[i], "-verbose")) || + (!strcmp(argv[i], "--verbose"))) { + xsltSetGenericDebugFunc(stderr, NULL); + } else if ((!strcmp(argv[i], "-o")) || + (!strcmp(argv[i], "-output")) || + (!strcmp(argv[i], "--output"))) { + i++; + output = argv[i++]; + } else if ((!strcmp(argv[i], "-V")) || + (!strcmp(argv[i], "-version")) || + (!strcmp(argv[i], "--version"))) { + printf("Using libxml %s and libxslt %s\n", + xmlParserVersion, xsltEngineVersion); + printf + ("xsltproc was compiled against libxml %d and libxslt %d\n", + LIBXML_VERSION, LIBXSLT_VERSION); + printf("libxslt %d was compiled against libxml %d\n", + xsltLibxsltVersion, xsltLibxmlVersion); + } else if ((!strcmp(argv[i], "-repeat")) + || (!strcmp(argv[i], "--repeat"))) { + if (repeat == 0) + repeat = 20; + else + repeat = 100; + } else if ((!strcmp(argv[i], "-novalid")) || + (!strcmp(argv[i], "--novalid"))) { + novalid++; + } else if ((!strcmp(argv[i], "-noout")) || + (!strcmp(argv[i], "--noout"))) { + noout++; #ifdef LIBXML_DOCB_ENABLED - } else if ((!strcmp(argv[i], "-docbook")) || - (!strcmp(argv[i], "--docbook"))) { - docbook++; + } else if ((!strcmp(argv[i], "-docbook")) || + (!strcmp(argv[i], "--docbook"))) { + docbook++; #endif #ifdef LIBXML_HTML_ENABLED - } else if ((!strcmp(argv[i], "-html")) || - (!strcmp(argv[i], "--html"))) { - html++; + } else if ((!strcmp(argv[i], "-html")) || + (!strcmp(argv[i], "--html"))) { + html++; #endif - } else if ((!strcmp(argv[i], "-timing")) || - (!strcmp(argv[i], "--timing"))) { - timing++; - } else if ((!strcmp(argv[i], "-warnnet")) || - (!strcmp(argv[i], "--warnnet"))) { - xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader); - } else if ((!strcmp(argv[i], "-nonet")) || - (!strcmp(argv[i], "--nonet"))) { - xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader); - nonet = 1; + } else if ((!strcmp(argv[i], "-timing")) || + (!strcmp(argv[i], "--timing"))) { + timing++; + } else if ((!strcmp(argv[i], "-warnnet")) || + (!strcmp(argv[i], "--warnnet"))) { + xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader); + } else if ((!strcmp(argv[i], "-nonet")) || + (!strcmp(argv[i], "--nonet"))) { + xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader); + nonet = 1; #ifdef LIBXML_CATALOG_ENABLED - } else if ((!strcmp(argv[i], "-catalogs")) || - (!strcmp(argv[i], "--catalogs"))) { - const char *catalogs; + } else if ((!strcmp(argv[i], "-catalogs")) || + (!strcmp(argv[i], "--catalogs"))) { + const char *catalogs; - catalogs = getenv("SGML_CATALOG_FILES"); - if (catalogs == NULL) { - fprintf(stderr, "Variable $SGML_CATALOG_FILES not set\n"); - } else { - xmlLoadCatalogs(catalogs); - } + catalogs = getenv("SGML_CATALOG_FILES"); + if (catalogs == NULL) { + fprintf(stderr, "Variable $SGML_CATALOG_FILES not set\n"); + } else { + xmlLoadCatalogs(catalogs); + } #endif #ifdef LIBXML_XINCLUDE_ENABLED - } else if ((!strcmp(argv[i], "-xinclude")) || - (!strcmp(argv[i], "--xinclude"))) { - xinclude++; - xsltSetXIncludeDefault(1); + } else if ((!strcmp(argv[i], "-xinclude")) || + (!strcmp(argv[i], "--xinclude"))) { + xinclude++; + xsltSetXIncludeDefault(1); #endif - } else if ((!strcmp(argv[i], "-param")) || - (!strcmp(argv[i], "--param"))) { - i++; - params[nbparams++] = argv[i++]; - params[nbparams++] = argv[i]; - if (nbparams >= 16) { - fprintf(stderr, "too many params\n"); - return(1); - } - } else if ((!strcmp(argv[i], "-maxdepth")) || - (!strcmp(argv[i], "--maxdepth"))) { - int value; - i++; - if (sscanf(argv[i], "%d", &value) == 1) { - if (value > 0) - xsltMaxDepth = value; - } - } else { - fprintf(stderr, "Unknown option %s\n", argv[i]); - usage(argv[0]); - return(1); - } + } else if ((!strcmp(argv[i], "-param")) || + (!strcmp(argv[i], "--param"))) { + i++; + params[nbparams++] = argv[i++]; + params[nbparams++] = argv[i]; + if (nbparams >= 16) { + fprintf(stderr, "too many params\n"); + return (1); + } + } else if ((!strcmp(argv[i], "-maxdepth")) || + (!strcmp(argv[i], "--maxdepth"))) { + int value; + + i++; + if (sscanf(argv[i], "%d", &value) == 1) { + if (value > 0) + xsltMaxDepth = value; + } + } else { + fprintf(stderr, "Unknown option %s\n", argv[i]); + usage(argv[0]); + return (1); + } } params[nbparams] = NULL; xmlSubstituteEntitiesDefault(1); - if (novalid == 0) /* TODO XML_DETECT_IDS | XML_COMPLETE_ATTRS */ - xmlLoadExtDtdDefaultValue = 6; + if (novalid == 0) /* TODO XML_DETECT_IDS | XML_COMPLETE_ATTRS */ + xmlLoadExtDtdDefaultValue = 6; else - xmlLoadExtDtdDefaultValue = 0; - for (i = 1; i < argc ; i++) { - if ((!strcmp(argv[i], "-maxdepth")) || - (!strcmp(argv[i], "--maxdepth"))) { - i++; - continue; - } - if ((!strcmp(argv[i], "-param")) || - (!strcmp(argv[i], "--param"))) { - i += 2; + xmlLoadExtDtdDefaultValue = 0; + for (i = 1; i < argc; i++) { + if ((!strcmp(argv[i], "-maxdepth")) || + (!strcmp(argv[i], "--maxdepth"))) { + i++; + continue; + } else if ((!strcmp(argv[i], "-o")) || + (!strcmp(argv[i], "-output")) || + (!strcmp(argv[i], "--output"))) { + i++; continue; } - if ((argv[i][0] != '-') || (strcmp(argv[i], "-") == 0)) { - if (timing) - gettimeofday(&begin, NULL); - cur = xsltParseStylesheetFile((const xmlChar *)argv[i]); - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - fprintf(stderr, "Parsing stylesheet %s took %ld ms\n", - argv[i], msec); - } - if (cur != NULL) { - if (cur->indent == 1) - xmlIndentTreeOutput = 1; - else - xmlIndentTreeOutput = 0; - i++; - } - break; - - } + if ((!strcmp(argv[i], "-param")) || (!strcmp(argv[i], "--param"))) { + i += 2; + continue; + } + if ((argv[i][0] != '-') || (strcmp(argv[i], "-") == 0)) { + if (timing) + gettimeofday(&begin, NULL); + cur = xsltParseStylesheetFile((const xmlChar *) argv[i]); + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, "Parsing stylesheet %s took %ld ms\n", + argv[i], msec); + } + if (cur != NULL) { + if (cur->indent == 1) + xmlIndentTreeOutput = 1; + else + xmlIndentTreeOutput = 0; + i++; + } + break; + + } } if ((cur != NULL) && (cur->errors == 0)) { - for (;i < argc ; i++) { - if (timing) - gettimeofday(&begin, NULL); + for (; i < argc; i++) { + if (timing) + gettimeofday(&begin, NULL); #ifdef LIBXML_HTML_ENABLED - if (html) - doc = htmlParseFile(argv[i], NULL); - else + if (html) + doc = htmlParseFile(argv[i], NULL); + else #endif #ifdef LIBXML_DOCB_ENABLED - if (docbook) - doc = docbParseFile(argv[i], NULL); - else + if (docbook) + doc = docbParseFile(argv[i], NULL); + else #endif - doc = xmlParseFile(argv[i]); - if (doc == NULL) { - fprintf(stderr, "unable to parse %s\n", argv[i]); - continue; - } - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - fprintf(stderr, "Parsing document %s took %ld ms\n", - argv[i], msec); - } + doc = xmlParseFile(argv[i]); + if (doc == NULL) { + fprintf(stderr, "unable to parse %s\n", argv[i]); + continue; + } + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, "Parsing document %s took %ld ms\n", + argv[i], msec); + } #ifdef LIBXML_XINCLUDE_ENABLED - if (xinclude) { - if (timing) - gettimeofday(&begin, NULL); - xmlXIncludeProcess(doc); - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - fprintf(stderr, "XInclude processing %s took %ld ms\n", - argv[i], msec); - } - } + if (xinclude) { + if (timing) + gettimeofday(&begin, NULL); + xmlXIncludeProcess(doc); + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, "XInclude processing %s took %ld ms\n", + argv[i], msec); + } + } #endif - if (timing) - gettimeofday(&begin, NULL); - if (repeat) { - int j; - for (j = 1;j < repeat; j++) { - res = xsltApplyStylesheet(cur, doc, params); - xmlFreeDoc(res); - xmlFreeDoc(doc); + if (timing) + gettimeofday(&begin, NULL); + if (output == NULL) { + if (repeat) { + int j; + + for (j = 1; j < repeat; j++) { + res = xsltApplyStylesheet(cur, doc, params); + xmlFreeDoc(res); + xmlFreeDoc(doc); #ifdef LIBXML_HTML_ENABLED - if (html) - doc = htmlParseFile(argv[i], NULL); - else + if (html) + doc = htmlParseFile(argv[i], NULL); + else #endif #ifdef LIBXML_DOCB_ENABLED - if (docbook) - doc = docbParseFile(argv[i], NULL); - else + if (docbook) + doc = docbParseFile(argv[i], NULL); + else #endif - doc = xmlParseFile(argv[i]); - } - } - res = xsltApplyStylesheet(cur, doc, params); - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - if (repeat) - fprintf(stderr, - "Applying stylesheet %d times took %ld ms\n", - repeat, msec); - else - fprintf(stderr, "Applying stylesheet took %ld ms\n", - msec); - } - xmlFreeDoc(doc); - if (res == NULL) { - fprintf(stderr, "no result for %s\n", argv[i]); - continue; - } - if (noout) { - xmlFreeDoc(res); - continue; - } + doc = xmlParseFile(argv[i]); + } + } + res = xsltApplyStylesheet(cur, doc, params); + if (timing) { + long msec; + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + if (repeat) + fprintf(stderr, + "Applying stylesheet %d times took %ld ms\n", + repeat, msec); + else + fprintf(stderr, + "Applying stylesheet took %ld ms\n", msec); + } + xmlFreeDoc(doc); + if (res == NULL) { + fprintf(stderr, "no result for %s\n", argv[i]); + continue; + } + if (noout) { + xmlFreeDoc(res); + continue; + } #ifdef LIBXML_DEBUG_ENABLED - if (debug) - xmlDebugDumpDocument(stdout, res); - else { + if (debug) + xmlDebugDumpDocument(stdout, res); + else { #endif - if (cur->methodURI == NULL) { - if (timing) - gettimeofday(&begin, NULL); - xsltSaveResultToFile(stdout, res, cur); - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - fprintf(stderr, "Saving result took %ld ms\n", - msec); - } - } else { - if (xmlStrEqual(cur->method, (const xmlChar *)"xhtml")) { - fprintf(stderr, "non standard output xhtml\n"); - if (timing) - gettimeofday(&begin, NULL); - xsltSaveResultToFile(stdout, res, cur); - if (timing) { - long msec; - gettimeofday(&end, NULL); - msec = end.tv_sec - begin.tv_sec; - msec *= 1000; - msec += (end.tv_usec - begin.tv_usec) / 1000; - fprintf(stderr, "Saving result took %ld ms\n", - msec); - } - } else { - fprintf(stderr, "Unsupported non standard output %s\n", - cur->method); - } - } + if (cur->methodURI == NULL) { + if (timing) + gettimeofday(&begin, NULL); + xsltSaveResultToFile(stdout, res, cur); + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, "Saving result took %ld ms\n", + msec); + } + } else { + if (xmlStrEqual + (cur->method, (const xmlChar *) "xhtml")) { + fprintf(stderr, "non standard output xhtml\n"); + if (timing) + gettimeofday(&begin, NULL); + xsltSaveResultToFile(stdout, res, cur); + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += + (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, + "Saving result took %ld ms\n", + msec); + } + } else { + fprintf(stderr, + "Unsupported non standard output %s\n", + cur->method); + } + } #ifdef LIBXML_DEBUG_ENABLED - } + } #endif - xmlFreeDoc(res); - } - xsltFreeStylesheet(cur); + xmlFreeDoc(res); + } else { + xsltRunStylesheet(cur, doc, params, output, NULL, NULL); + if (timing) { + long msec; + + gettimeofday(&end, NULL); + msec = end.tv_sec - begin.tv_sec; + msec *= 1000; + msec += (end.tv_usec - begin.tv_usec) / 1000; + fprintf(stderr, + "Running stylesheet and saving result took %ld ms\n", + msec); + } + xmlFreeDoc(doc); + } + } + xsltFreeStylesheet(cur); } xmlCleanupParser(); xmlMemoryDump(); - return(0); + return (0); } diff --git a/tests/docbook/Makefile.am b/tests/docbook/Makefile.am index 5f3ab39..2eef7e4 100644 --- a/tests/docbook/Makefile.am +++ b/tests/docbook/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -all: single # Avoid doing the test in normal pass +all: single xtchunk # Avoid doing the test in normal pass $(top_builddir)/libxslt/xsltproc: @(cd ../../libxslt ; make xsltproc) @@ -55,6 +55,25 @@ single: echo ; \ done ) +xtchunk: + @(echo > .memdump) + @(for i in $(srcdir)/test/gdp-handbook.xml ; do \ + echo "Texting HTML chunking on $$i :" ; \ + html=$(srcdir)/result/html/`basename $$i .xml`.html; \ + $(top_builddir)/libxslt/xsltproc -o $(srcdir)/result/xtchunk/html/gdp-handbook $(srcdir)/html/xtchunk.xsl $$i ; \ + for html in $(srcdir)/result/xtchunk/html/*.html ; do \ + orig=$(srcdir)/result/xtchunk/html/`basename $$html .html`.orig ;\ + if [ -f $$orig ] ; then \ + grep -v id < $$html > $$html.noid ; \ + grep -v id < $$orig > $$orig.noid ; \ + diff $$orig.noid $$html.noid ; \ + rm -f $$html.noid $$orig.noid $$html; \ + else mv $$html $$orig ; fi ; \ + done ; \ + grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" || true; \ + rm -f $(srcdir)/result/xtchunk/html/gdp-handbook ; \ + done ) + # # The full set of tests # diff --git a/tests/docbook/result/xtchunk/html/apa.orig b/tests/docbook/result/xtchunk/html/apa.orig new file mode 100644 index 0000000..e1a1c77 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/apa.orig @@ -0,0 +1,789 @@ + + + + +A. Document Templates + + + + + + + +
+ + + + + + + +
A. Document Templates
+Prev   Next +
+
+
+
+

+A. 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. + 

+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+        <!-- if not using PNG graphic, replace reference above with
+             .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
+         -->
+<!ENTITY version "1.0.53">
+        <!-- replace version above with actual application version number-->
+	<!--  Template Version: 1.0.1  (do not remove this line) -->
+]>
+
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+  Documentation Project Team. Please use it for writing GNOME
+  documentation, making obvious changes. In particular, all the words
+  written in UPPERCASE (with the exception of GNOME) should be
+  replaced. As for "legalnotice", please leave the reference
+  unchanged.
+
+  Remember that this is a guide, rather than a perfect model to follow
+  slavishly. Make your manual logical and readable.  And don't forget
+  to remove these comments in your final documentation!  ;-)
+  -->
+
+<!-- =============Document Header ============================= -->
+
+<article id="index"> <!-- please do not change the id -->
+
+  <artheader>
+    <title>MY-GNOME-APP</title>
+    <copyright>
+      <year>2000</year>
+      <holder>ME-THE-AUTHOR</holder>
+    </copyright>
+
+  <!-- translators: uncomment this:
+
+  <copyright>
+   <year>2000</year>
+   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+  </copyright>
+
+   -->
+
+  <!-- do not put authorname in the header except in copyright - use
+  section "authors" below -->
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this
+        document under the terms of the <citetitle>GNU Free
+        Documentation License</citetitle>, 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 <citetitle>GNU Free
+        Documentation License</citetitle> from the Free Software
+        Foundation by visiting <ulink type="http"
+        url="http://www.fsf.org">their Web site</ulink> or by writing
+        to: Free Software Foundation, Inc., 59 Temple Place - Suite
+        330, Boston, MA 02111-1307, USA.
+      </para>
+      <para>
+        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.
+      </para>
+    </legalnotice>
+
+  <!-- this is the version of manual, not application --> 
+    <releaseinfo>
+       This is version 1.0 of MY-GNOME-APP manual.
+    </releaseinfo>
+
+  </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ <!-- ============= Introduction ============================== -->
+  <sect1 id="intro">
+    <title>Introduction</title>
+
+    <para>
+     <application>MY-GNOME-APP</application> 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 <application>MY-GNOME-APP</application>
+     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.
+    </para>
+    <para>
+      It also allows you to save and print theorem proofs and to add
+      comments to the proofs it produces.
+    </para>
+
+    <para>
+      To run <application>MY-GNOME-APP</application>, select
+      <menuchoice>
+	<guisubmenu>SUBMENU</guisubmenu>
+	<guimenuitem>MY-GNOME-APP</guimenuitem>
+      </menuchoice>
+      from the <guimenu>Main Menu</guimenu>, or type
+      <command>MYGNOMEAPP</command> on the command line.
+  </para>
+
+    <para>
+      <application>MY-GNOME-APP</application> is included in the
+      <filename>GNOME-PACKAGE</filename> package, which is part of the
+      GNOME desktop environment. This document describes version
+      &version; of <application>MY-GNOME-APP</application>.
+    </para>
+  </sect1>
+
+
+ <!-- ================ Usage ================================ -->
+ <!-- This section should describe basic usage of the application. -->
+
+  <sect1 id="usage">
+    <title>Using MY-GNOME-APP</title>
+    <para>
+      <application>MY-GNOME-APP</application> can be used to produce a
+      perfect proof of <emphasis>any</emphasis> 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
+      <application>MY-GNOME-APP</application>.
+    </para>
+
+    <!-- ========= Basic Usage =========================== -->
+    <sect2 id="mainwin">
+      <title>Basic usage</title>
+      <para>
+        Starting <application>MY-GNOME-APP</application> opens the
+        <interface>Main window</interface>, shown in <xref
+        linkend="mainwindow-fig">. The window is at first empty.
+
+        <!-- ==== Figure ==== -->
+        <figure id="mainwindow-fig">
+	  <title>MY-GNOME-APP Main Window</title>
+	  <screenshot>
+	    <screeninfo>MY-GNOME-APP Main Window</screeninfo>
+	    <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
+            </graphic>
+	  </screenshot>
+	</figure>
+    <!-- ==== End of Figure ==== -->
+      </para> 
+
+
+ <!-- For this app, one could put "proving" or "edit" (probably even
+      both of them) as sect2's seperate from the main window
+      section. Since they were both so closely involved with the main
+      window, I decided to have them as sect3's isntead. Judgement
+      call. -->
+
+      <sect3 id="proving">
+	<title>Proving a Theorem</title>
+	<para>
+          To get a proof of a theorem, select
+          <menuchoice>
+	    <guisubmenu>File</guisubmenu>
+	    <guimenuitem>New</guimenuitem>
+	  </menuchoice>,
+            which will
+	    bring up the <interface>New Proof</interface> dialog box.
+	    Enter the statement of the theorem in the
+	    <guilabel>Theorem statement</guilabel> field, select your
+	    desired proof type from the drop-down menu, and and press
+	    <guibutton>Prove!</guibutton>.
+        </para>
+	<para>
+          If <application>MY-GNOME-APP</application> cannot prove the
+          theorem by the method you have chosen, or if you have not
+          selected a proof type at all,
+          <application>MY-GNOME-APP</application> 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: 
+     
+                <variablelist>
+	    <varlistentry>
+	      <term>Deduction</term>
+	      <listitem>
+		<para>
+                  This is a proof method that is generally accepted
+                  for full credit by Logic professors.
+                </para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+            <term>Induction</term>
+	    <listitem>
+	      <para>
+                This logical style will also earn you full credit on
+                your homework.
+             </para>
+	    </listitem>
+            </varlistentry>
+	    <varlistentry>
+	      <term>Dialog</term>
+	      <listitem>
+	      <para>
+                This logical method is best for Philosophy classes,
+                and will probably only merit partial credit on Logic
+                or Mathematics homework.
+              </para>
+	    </listitem>
+            </varlistentry>
+            <varlistentry>
+	      <term>Confusion</term>
+	      <listitem>
+	      <para>
+                Suitable only for political debates, battles of wits
+                against the unarmed, and Philosophy classes focusing
+                on the works of Kant. Use with caution.
+              </para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+          </para>
+
+   <!-- You might want to include a note, warning, or tip, e.g. -->
+	
+	<warning>
+	  <title>Proving Incorrect Theorms</title>
+	  <para>
+            <application>MY-GNOME-APP</application> 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
+            <application>MY-GNOME-APP</application> to prove its
+            logical inverse.
+          </para>
+	</warning>
+      </sect3>
+      <sect3 id="editing">
+	<title>Editing Proofs</title>
+	<para>
+          Once you have proven the theorem, it will be displayed in
+          the <interface>main window</interface>.  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.
+        </para>
+	<para>
+          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 <guisubmenu>Style</guisubmenu> submenu of the
+          <guimenu>Edit</guimenu> menu.
+          <application>MY-GNOME-APP</application> will convert the
+          text to that style.
+        </para>
+        <para>
+          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.
+        </para>
+
+	<note>
+	  <title>Altering The Proofs Themselves</title>
+          <para>
+            <application>MY-GNOME-APP</application> does not allow you
+            to alter a proof it has produced itself.  You can, save
+            your proof as a plain text file (using the
+            <guimenuitem>Save as...</guimenuitem> menu), and alter it
+            that way.  Be aware, however, that
+            <application>MY-GNOME-APP</application> uses its own file
+            format for saved proofs, and cannot re-open a file unless
+            it is in the .mga format.
+          </para>
+	</note>
+      </sect3>
+
+
+  <!-- If there are other functions performed from the main window,
+       they belong here.   -->
+
+    </sect2>
+ 
+    <!-- ========================================================= 
+      Additional Sect2's should describe additional windows, such as
+      larger dialog boxes, or functionality that differs significantly
+      from the most immediate functions of the application. Make the
+      structure logical.
+      =============================================================  -->
+
+
+    <sect2 id="toolbar">
+      <title>Toolbar</title>
+      <para>
+        The toolbar (shown in <xref linkend="figure-usage-toolbar">)
+        provides access to several commonly used routines.
+        <figure id="figure-usage-toolbar">
+	  <title>MY-GNOME-APP Toolbar</title>
+	  <screenshot>
+	    <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
+	    <graphic fileref="usage-toolbar.png" format="png"></graphic>
+	  </screenshot>
+	</figure>
+        <variablelist>
+	  <varlistentry>
+	    <term>New</term>
+	    <listitem>
+	      <para>
+                Brings up the <interface>New Theorem</interface>
+                dialog.
+              </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Open</term>
+	    <listitem>
+	      <para>
+                 Open an exisiting theorem you want to prove, or a
+                 completed proof you wish to print or format.
+               </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Save</term>
+	    <listitem>
+	      <para>
+	         Save the current theorem permanently in a
+	         file.
+               </para>
+	    </listitem> 
+	  </varlistentry>
+	</variablelist>
+       </para>
+    </sect2>
+    <!-- ========= Menus =========================== --> 
+
+    <sect2 id="menubar">
+
+       <!-- Describing the menubar ensures comprehensive feature
+       coverage. Nest itemizedlists inside variablelists so that each
+       menu is easily located by indexing software. Proper indentation
+       makes it easier! -->
+
+      <title>Menus</title>
+      <para>
+	The menu bar, located at the top of the <interface>Main
+	Window</interface>, contains the following menus:
+       </para>
+      <variablelist>
+	<varlistentry>
+	  <term><guimenu>File</guimenu></term>
+	  <listitem>
+	    <para>
+	       This menu contains:
+	       <itemizedlist>
+		<listitem>
+		  <para>
+	            <menuchoice>
+		      <shortcut>
+			<keycap>F3</keycap>
+		      </shortcut>
+		      <guimenuitem>Open</guimenuitem>
+		     </menuchoice>
+	             &mdash; This opens a file which is saved on your computer.
+	           </para>
+		</listitem>
+		<listitem>
+		  <para>
+	             <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Save</guimenuitem>
+		    </menuchoice>
+	            &mdash; This saves your file.
+	          </para>
+		</listitem>
+		<listitem>
+		  <para>
+	             <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Close</guimenuitem>
+		    </menuchoice>
+	            &mdash; This closes your file.
+	          </para>
+		</listitem>
+		<listitem>
+		  <para>
+	            <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Exit</guimenuitem>
+		    </menuchoice>
+	            &mdash; This quits the application.
+	          </para>
+		</listitem>
+	      </itemizedlist>
+	  </para>
+	  </listitem>
+	</varlistentry>
+	
+	<varlistentry>
+	  <term><guimenu>Edit</guimenu></term>
+	  <listitem>
+	    <para>
+	   This menu contains:
+	   <itemizedlist>
+		<listitem>
+		  <para>
+	            <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Cut</guimenuitem>
+		    </menuchoice>
+	            &mdash; This removes any text or data which is selected and
+	            places it in the buffer.
+	          </para>
+		</listitem>
+		<listitem>
+		  <para>
+	            <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Copy</guimenuitem>
+		    </menuchoice>
+	            &mdash; This copies any text or data which is selected into
+	            the buffer.
+	          </para>
+		</listitem>
+		<listitem>
+		  <para>
+	           <menuchoice>
+		      <shortcut>
+			<keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
+		      </shortcut>
+		      <guimenuitem>Paste</guimenuitem>
+		    </menuchoice>
+	            &mdash; This pastes any text or data which is copied into
+	            the buffer.
+	        </para>
+		</listitem>
+		<listitem>
+		  <para>
+	             <guimenuitem>COMMAND1&hellip;</guimenuitem>
+	             &mdash; This opens the <interface>COMMAND1</interface>
+	             dialog, which is used to ....
+	          </para>
+		</listitem>
+		<listitem>
+		  <para>
+	            <guimenuitem>COMMAND2</guimenuitem>
+	            &mdash; This ....
+	          </para>
+		</listitem>
+	      </itemizedlist>
+	    </para>
+	  </listitem>
+	</varlistentry>
+	
+
+	<varlistentry>
+	  <term><guimenu>Settings</guimenu></term>
+	  <listitem>
+	    <para>
+	   This menu contains:
+	   <itemizedlist>
+		<listitem>
+		  <para>
+	      <guimenuitem>Preferences&hellip;</guimenuitem>
+	       &mdash; This opens the <link
+	       linkend="prefs"><interface>Preferences
+	       Dialog</interface></link>, which allows you to configure
+	       many settings.
+	     </para>
+		</listitem>
+		<listitem>
+		  <para>
+	            <guimenuitem>COMMAND3</guimenuitem> &mdash;
+    	            This command does something.
+    	    	   </para>
+		</listitem>
+	      </itemizedlist>
+	    </para>
+	  </listitem>
+	</varlistentry>
+	
+	<varlistentry>
+	  <term><guimenu>Help</guimenu></term>
+	  <listitem>
+	    <para>
+	      This menu contains:
+	       <itemizedlist>
+		<listitem>
+		  <para>
+	             <guimenuitem>Manual</guimenuitem> &mdash; This
+    	              opens the <application>GNOME Help
+    	              Browser</application> and displays this manual.
+	          </para>
+		</listitem>
+		
+		<listitem>
+		  <para>
+	            <guimenuitem>About</guimenuitem> &mdash; This
+    	            opens the <interface>About</interface> dialog
+    	            which shows basic information about
+    	            <application>MY-GNOME-APP</application>, such as
+    	            the author's name, the application version number,
+    	            and the URL for the application's Web page if one
+    	            exists.
+	          </para>
+		</listitem>
+	      </itemizedlist>
+            </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+  </sect1>
+
+
+
+ <!-- ============= Customization ============================= -->
+
+ <sect1 id="prefs">
+  <title>Customization</title>
+  <para>
+   To change the application settings, select
+   <menuchoice>
+    <guimenu>Settings</guimenu>
+    <guimenuitem>Preferences...</guimenuitem>
+   </menuchoice>.  This opens the
+   <interface>Preferences</interface> dialog, shown in <xref
+   linkend="preferences-fig">.
+  </para>
+
+  <figure id="preferences-fig">
+   <title>Preferences Dialog</title>
+   <screenshot>
+    <screeninfo>Preferences Dialog</screeninfo>
+    <graphic fileref="SCREENSHOT" format="png"
+     srccredit="ME">
+    </graphic>
+   </screenshot>
+  </figure>
+
+  <para>
+   The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
+   
+   <!--many people use itemizedlists in cases like this. Variablelists
+   are more appropriate -->
+
+      <variablelist>
+	<varlistentry>
+	  <term> <guilabel>Default Text Style</guilabel></term>
+	  <listitem>
+	    <para>
+              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.
+            </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>(Configuration Item Label)</term>
+	  <listitem>
+	    <para>
+             (Description of Configuration)
+             </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>(Configuration Item Label)</term>
+	  <listitem>
+	    <para>
+             (Description of Configuration)
+             </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+
+    <para>
+     The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
+       <variablelist>
+	<varlistentry>
+	  <term>(Configuration Item Label)</term>
+	  <listitem>
+	    <para>
+             (Description of Configuration)
+             </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>(Configuration Item Label)</term>
+	  <listitem>
+	    <para>
+             (Description of Configuration)
+             </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+
+  <para>
+    After you have made all the changes you want, click on
+    <guibutton>OK</guibutton> to apply the changes and close the
+    <interface>Properties</interface> dialog. To cancel the changes
+    and return to previous values, click the
+    <guibutton>Close</guibutton> button.
+  </para>
+
+ </sect1>
+
+
+ <!-- ============= Various Sections ============================= -->
+
+ <!-- Here you should add, if necessary, several more sect1's,
+ describing other windows (besides the main one), file formats,
+ preferences dialogs,  etc. as appropriate. Try not to make any of
+ these sections too long. -->
+
+
+ <!-- ============= Bugs ================================== -->
+ <!-- This section should describe known bugs and limitations of
+      the program if there are any - please be frank and list all
+      problems you know of. -->
+ <sect1 id="bugs">
+  <title>Known Bugs and Limitations</title>
+  <para>
+   This application has no known bugs.
+  </para>
+ </sect1>
+
+
+<!-- ============= Authors ================================ -->
+
+ <sect1 id="authors">
+  <title>Authors</title>
+  <para>
+   <application>MY-GNOME-APP</application> was written by GNOME-HACKER
+   (<email>hacker@gnome.org</email>). To find more information about
+   <application>MY-GNOME-APP</application>, please visit the <ulink
+   url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
+   page</ulink>.  Please send all comments, suggestions, and bug
+   reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+   bug tracking database</ulink>. (Instructions for submitting bug
+   reports can be found <ulink
+   url="http://bugs.gnome.org/Reporting.html" type="http">
+   on-line</ulink>.)  You can also use <application>Bug Report
+   Tool</application> (<command>bug-buddy</command>), available in the
+   <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+   Menu</guimenu>, for submitting bug reports.
+  </para>
+
+  <para>
+   This manual was written by ME
+   (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+   suggestions regarding this manual to the <ulink type="http"
+   url="http://developer.gnome.org/projects/gdp">GNOME Documentation 
+   Project</ulink> by sending an email to 
+   <email>docs@gnome.org</email>. You can also add your comments online 
+   by using the <ulink type="http" 
+   url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
+   Table</ulink>.
+  </para>
+
+  <!-- For translations: uncomment this:
+
+  <para>
+   Latin translation was done by ME
+   (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
+   suggestions regarding this translation to SOMEWHERE.
+  </para>
+
+  -->
+
+ </sect1>
+
+
+ <!-- ============= Application License ============================= -->
+
+ <sect1 id="license">
+  <title>License</title>
+  <para>
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the <citetitle>GNU General Public
+   License</citetitle> as published by the Free Software Foundation;
+   either version 2 of the License, or (at your option) any later
+   version.
+  </para>
+  <para>
+   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
+   <citetitle>GNU General Public License</citetitle> for more details.
+  </para>
+  <para>
+   A copy of the <citetitle>GNU General Public License</citetitle> is
+   included as an appendix to the <citetitle>GNOME Users
+   Guide</citetitle>.  You may also obtain a copy of the
+   <citetitle>GNU General Public License</citetitle> from the Free
+   Software Foundation by visiting <ulink type="http"
+   url="http://www.fsf.org">their Web site</ulink> or by writing to
+   <address>
+    Free Software Foundation, Inc.
+    <street>59 Temple Place</street> - Suite 330
+    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+    <country>USA</country>
+   </address>
+  </para>
+ </sect1>
+</article>
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Resources Up Template 2: Applet Manual For GNOME 1.x
+
+ + diff --git a/tests/docbook/result/xtchunk/html/apas17.orig b/tests/docbook/result/xtchunk/html/apas17.orig new file mode 100644 index 0000000..c413034 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/apas17.orig @@ -0,0 +1,371 @@ + + + + +Template 2: Applet Manual For GNOME 1.x + + + + + + + +
+ + + + + + + +
Template 2: Applet Manual For GNOME 1.x
+Prev A. Document Templates Next +
+
+
+
+

+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. + 

+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+ <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
+        <!--  Template Version: 1.0.1  (do not remove this line) -->
+]>
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+  Documentation Project Team. Please use it for writing GNOME
+  documentation, making obvious changes. In particular, all the words
+  written in UPPERCASE (with the exception of GNOME) should be
+  replaced. As for "legalnotice", please leave the reference
+  unchanged,make sure to add/remove trademarks to the list as
+  appropriate for your document.
+
+  Please don't forget to remove these comments in your final documentation,
+  thanks ;-).
+-->
+
+<article id="index"> <!-- please do not change the id -->
+
+ <!-- ============= Document Header ============================= -->
+ <artheader> 
+  <title>APPLETNAME Applet</title>
+  <copyright>
+   <year>2000</year>
+   <holder>YOURFULLNAME</holder>
+  </copyright>
+
+  <!-- translators: uncomment this:
+
+  <copyright>
+   <year>2000</year>
+   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+  </copyright>
+
+   -->
+
+  <!-- do not put authorname in the header except in copyright - use
+  section "authors" below -->
+
+  <legalnotice>
+   <para>
+    Permission is granted to copy, distribute and/or modify this
+    document under the terms of the <citetitle>GNU Free Documentation
+    License</citetitle>, 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 <citetitle>GNU Free Documentation License</citetitle> from
+    the Free Software Foundation by visiting <ulink type="http"
+    url="http://www.fsf.org">their Web site</ulink> or by writing to:
+    Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+    Boston, MA 02111-1307, USA.
+   </para>
+   <para>
+    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.
+   </para>
+  </legalnotice>
+
+  <releaseinfo>
+   This is version XXX of the APPLETNAME applet manual.
+  </releaseinfo>
+ </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ &APPLETNAME.sgml;
+
+</article>
+
+
+
+
+
+
+ 
+
+        <!--  Template Version: 1.0.1  (do not remove this line) -->
+
+ <sect1 id="APPLET">
+  <title>APPLET Applet</title>
+
+  <para>
+   <application>APPLET</application> applet, shown in <xref
+   linkend="APPLETapplet-fig">, allows you to &hellip;.  To add this
+   applet to a <interface>Panel</interface>, 
+   right-click on the <interface>Panel</interface> and choose
+   <menuchoice>
+    <guimenu>Panel</guimenu>
+    <guisubmenu>Add to panel</guisubmenu>
+    <guisubmenu>Applet</guisubmenu>
+    <guisubmenu>SECTION</guisubmenu>
+    <guimenuitem>APPLET</guimenuitem>
+   </menuchoice>.
+  </para>
+
+  <figure id="APPLETapplet-fig">
+   <title>APPLET Applet</title>
+   <screenshot>
+    <screeninfo>APPLET Applet</screeninfo>
+    <graphic format="png" fileref="APPLET_applet" 
+    srccredit="YOURNAME">
+    </graphic>
+   </screenshot>
+  </figure>
+
+  <!-- ============= Usage  ================================ -->
+  <sect2 id="APPLET-usage">
+   <title>Usage</title>
+   <para>
+    (Place a short description of how to use the applet here.)
+   </para>
+
+   <para>
+    Right-clicking on the applet brings up a menu containing the
+    following items:
+    <itemizedlist>
+
+     <listitem>
+      <para>
+       <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
+       opens the <link linkend="APPLET-prefs">
+       <guilabel>Properties</guilabel></link> dialog.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       <guimenuitem>Help</guimenuitem> &mdash;
+       displays this document.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       <guimenuitem>About&hellip;</guimenuitem> &mdash;
+       shows basic information about <application>APPLET
+       Applet</application>, including the applet's version and the
+       author's name.
+      </para>
+     </listitem>
+
+    </itemizedlist>
+   </para>
+  </sect2>
+
+
+  <!-- ============= Customization ============================= -->
+  <sect2 id="APPLET-prefs">
+    <title>Customization</title>
+    <para>
+      You can customize <application>APPLET</application>
+      applet by right-clicking on it and choosing
+      <guimenuitem>Properties&hellip;</guimenuitem>. This will open the
+      <interface>Properties</interface> dialog(shown in <xref
+      linkend="APPLET-settings-fig">), which allows you to
+      change various settings.
+    </para>
+
+    <figure id="APPLET-settings-fig">
+     <title>Properties dialog</title>
+     <screenshot>
+      <screeninfo>Properties dialog</screeninfo>
+      <graphic format="png" fileref="APPLET_settings"
+      srccredit="YOURNAME">
+      </graphic>
+     </screenshot>
+    </figure>
+
+    <para>
+     The properties are:
+     <itemizedlist>
+
+      <listitem>
+       <para>
+        (Configuration Item Label) &mdash; If this button is
+        checked&hellip;(description)
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
+        (Configuration Item Label) &mdash; Selecting this
+        button&hellip;(description)
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
+        (Configuration Item Label) &mdash; Enter the name of
+        &hellip;(description)
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+
+    <para> 
+      After you have made all the changes you want, click on
+      <guibutton>OK</guibutton> to apply the changes and close the
+      <interface>Properties</interface> dialog. To cancel the changes
+      and return to previous values, click the
+      <guibutton>Close</guibutton> button.
+    </para>
+  </sect2>
+
+
+  <!-- ============= Bugs ================================== -->
+  <!-- This section should describe known bugs and limitations of
+       the program if there are any - please be frank and list all
+       problems you know of -->
+  <sect2 id="bugs">
+   <title>Known Bugs and Limitations</title>
+   <para>
+    This applet has no known bugs.
+   </para>
+  </sect2>
+
+
+  <!-- ============= Authors ================================ -->
+
+  <sect2 id="authors">
+   <title>Authors</title>
+   <para>
+    <application>APPLET</application> was written by GNOME-HACKER
+    (<email>hacker@gnome.org</email>).  Please send all comments,
+    suggestions, and bug 
+    reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+    bug tracking database</ulink>. (Instructions for submitting bug
+    reports can be found <ulink
+    url="http://bugs.gnome.org/Reporting.html" type="http">
+    on-line</ulink>.  You can also use <application>Bug Report
+    Tool</application> (<command>bug-buddy</command>), available in the
+    <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+    Menu</guimenu>, for submitting bug reports.
+   </para>
+
+   <para>
+    This manual was written by ME
+    (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+    suggestions regarding this manual to the <ulink type="http"
+    url="http://developer.gnome.org/projects/gdp">GNOME Documentation
+    Project</ulink>  by sending an email to
+    <email>docs@gnome.org</email>. You can also submit comments online
+    by using the <ulink type="http"
+    url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
+    Status Table</ulink>.
+   </para>
+
+   <!-- For translations: uncomment this:
+
+   <para>
+    Latin translation was done by ME
+    (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
+    suggestions regarding this translation to SOMEWHERE.
+   </para>
+
+   -->
+
+  </sect2>
+
+
+  <!-- ============= Application License ============================= -->
+
+  <sect2 id="license">
+   <title>License</title>
+   <para>
+    This program is free software; you can redistribute it and/or
+    modify it under the terms of the <citetitle>GNU General Public
+    License</citetitle> as published by the Free Software Foundation;
+    either version 2 of the License, or (at your option) any later
+    version.
+   </para>
+   <para>
+    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
+    <citetitle>GNU General Public License</citetitle> for more details.
+   </para>
+   <para>
+    A copy of the <citetitle>GNU General Public License</citetitle> is
+    included as an appendix to the <citetitle>GNOME Users
+    Guide</citetitle>.  You may also obtain a copy of the
+    <citetitle>GNU General Public License</citetitle> from the Free
+    Software Foundation by visiting <ulink type="http"
+    url="http://www.fsf.org">their Web site</ulink> or by writing to
+    <address>
+     Free Software Foundation, Inc.
+     <street>59 Temple Place</street> - Suite 330
+     <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+     <country>USA</country>
+    </address>
+   </para>
+  </sect2>
+
+ </sect1>
+
+
+
+
+
+
+
+
+
+

+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
A. Document Templates Up Template 2: Applet Manual For GNOME 2.x
+
+ + diff --git a/tests/docbook/result/xtchunk/html/apas18.orig b/tests/docbook/result/xtchunk/html/apas18.orig new file mode 100644 index 0000000..425ce15 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/apas18.orig @@ -0,0 +1,672 @@ + + + + +Template 2: Applet Manual For GNOME 2.x + + + + + + +
+ + + + + + + +
Template 2: Applet Manual For GNOME 2.x
+Prev A. Document Templates 
+
+
+
+

+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. +

+

+ 

+
+<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
+
+]>
+
+<book id="gnome-applets">
+
+ <bookinfo>
+  <title>GNOME Applets</title>
+  <authorgroup>
+   <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
+   <author><firstname>John</firstname><surname>Fleck</surname></author>
+   <author><firstname>David</firstname><surname>Mason</surname>
+      <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
+    </author>
+    <author><firstname>Dan</firstname><surname>Mueth</surname></author>
+    <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
+  </authorgroup>
+  <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
+  <pubdate>2000</pubdate>
+  <copyright>
+   <year>2000</year>
+   <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
+    Alexander Kirillov</holder> 
+  </copyright>
+  <legalnotice>
+   <para>
+    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.
+   </para>
+   <para>
+    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.
+   </para>
+   <para>
+    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.
+   </para>
+   <para>
+    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.
+   </para>
+  </legalnotice>
+ </bookinfo>
+
+ <!-- #### Introduction ###### -->
+ <chapter id="applets-intro">
+  <title>Introduction</title> 
+
+  <!-- #### Intro | What Are Applets? ###### -->
+  <sect1 id="applets-what-are">
+   <title>What Are Applets?</title> 
+   <para>
+    Applets are one of the most popular and useful objects you can add
+    to your <interface>Panel</interface> to customize your desktop.
+    An applet is a small application which runs inside a small area of
+    your <interface>Panel</interface>. Applets have been written for
+    a wide range of purposes.  Some are very powerful interactive
+    tools, such as the <application>Tasklist</application> 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 <application>Battery Charge
+    Monitor</application>) or weather
+    information(see <application>GNOME Weather</application>).  Some
+    are simply for amusement(see <application>Fish</application>).
+   </para>
+
+   <para>
+    Applets are similar to swallowed applications in that both of them
+    reside within the <interface>Panel</interface>. However, 
+    swallowed applications are generally applications which were
+    not designed to run within the <interface>Panel</interface>.
+    Typically one will swallow an application which already exists in
+    the main <interface>desktop</interface> area, putting it into your
+    <interface>Panel</interface>.  The application will continue to
+    run in the <interface>Panel</interface> until you end the
+    application or  unswallow it,  placing it back onto the main part of
+    your desktop when you need to.
+   </para>
+
+   <para>
+    <figure id="example-applets-fig">
+     <title>Example Applets</title>
+     <screenshot>
+      <screeninfo>Example Applets</screeninfo>
+       <graphic fileref="example_applets" format="png"
+       srccredit="muet">
+       </graphic>
+     </screenshot>
+    </figure>
+    Several example applets are shown in <xref
+    linkend="example-applets-fig">.  From left to right, they are: (1)
+    <application>Mixer Applet</application>, which allows you to turn
+    on/off sound and control its volume by clicking on the applet.  (2)
+    <application>Sound Monitor</application> Applet, which displays
+    the current volume of sound being played and allows you to control
+    various sound features.  (3) <application>GTCD</application>
+    Applet, a CD player which has all its controls
+    available in the applet and displays the track and time. (4)
+    <application>Drive Mount</application> Applet, used to mount and
+    unmount drives with a single click of the mouse. (5)
+    <application>Desk Guide</application> which allows you to view
+    and control multiple virtual screens. (6)
+    <application>Tasklist</application> Applet which allows you to
+    control your various windows and applications.
+   </para>
+   <para>
+    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
+    <interface>Panels</interface> 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 <ulink type="http"
+     url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
+    Software Map</ulink> for lists of additional GNOME applications
+    and applets. 
+   </para>
+   <para>
+    As you read through the the rest of this chapter, you should try
+    adding and removing applets from your <interface>Panel</interface> and
+    experiment with them freely.  
+   </para>
+  </sect1>
+
+  <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
+  <sect1 id="applet-add-move-replace">
+   <title>Adding, Moving, and Removing Applets</title>
+
+   <sect2 id="adding-applets">   
+    <title>Adding Applets to a Panel</title>
+    <para>
+     To add an applet to a <interface>Panel</interface>, right-click
+     on the <interface>Panel</interface> and select 
+     <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
+     <guisubmenu>Applet</guisubmenu></menuchoice>. 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
+     <interface>Panel</interface>.
+    </para>
+   </sect2>
+
+   <sect2 id="moving-applets">
+    <title>Moving Applets In or Between Panels</title>
+    <para>
+     It is easy to move applets in a <interface>Panel</interface> or
+     between two <interface>Panels</interface>. 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 <interface>Panel</interface>
+     or between two <interface>Panels</interface> this way. If you
+     don't have a three-button mouse, just 
+     right-click on the applet and choose
+     <guimenuitem>Move</guimenuitem>. 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 <interface>Panels</interface> in the
+     <application>GNOME Control Center</application>: 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
+     <keycap>Shift</keycap> button (for "push" mode),
+     <keycap>Ctrl</keycap> (for "switched" mode), or
+     <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
+     objects without disturbing them) button while dragging.
+    </para>
+    <para>
+     To change the global Panel preferences, right-click on any applet
+     or <interface>Panel</interface> and select 
+     <menuchoice>
+      <guimenu>Panel</guimenu>
+      <guimenuitem>Global Preferences...</guimenuitem>
+     </menuchoice>.
+     The <guilabel>Default movement mode</guilabel> is set under the
+     <guilabel>Applets</guilabel> tab.
+    </para>
+   </sect2>
+
+   <sect2 id="removing-applets">
+    <title>Removing Applets from a Panel</title> 
+    <para>  
+     To remove an applet from a <interface>Panel</interface>,
+     right-click on the applet and select <guimenuitem>Remove from
+     panel...</guimenuitem>. 
+    </para>
+   </sect2>
+  </sect1>
+
+
+  <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
+  <sect1 id="right-click-pop-up-menu">
+   <title>The Right-Click Pop-Up Menu</title>
+   <para>
+    Clicking the right mouse button on any applet brings up
+    a <guimenu>pop-up menu</guimenu>. This 
+    menu always has certain standard menu items in it and
+    often has additional items which vary depending on the particular
+    applet. 
+   </para>
+   <sect2 id="standard-right-click-items"> 
+    <title>Standard Pop-Up Items</title>
+    <para>
+     All applets should have the following items in their right-click
+     <guimenu>pop-up menu</guimenu>:
+     <variablelist>
+      <varlistentry>
+       <term>Remove from panel</term>
+       <listitem>
+        <para>
+         The <guimenuitem>Remove from panel</guimenuitem> menu item
+         removes the applet from the <interface>Panel</interface>. 
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>Move</term>
+       <listitem>
+        <para>
+         After selecting <guimenuitem>Move</guimenuitem>, 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
+         <interface>Panels</interface> this way.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>Panel</term>
+       <listitem>
+        <para>
+         The <guisubmenu>Panel</guisubmenu> submenu contains various
+         items and submenus for adding and removing
+         <interface>Panels</interface> and applets and for changing
+         the configuration.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>About</term>
+       <listitem>
+        <para>
+         The <guimenuitem>About...</guimenuitem> 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. 
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>Help</term>
+       <listitem>
+        <para>
+         The <guimenuitem>Help</guimenuitem> menu item brings up the help
+         manual for the applet. 
+        </para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
+   </sect2>
+
+   <sect2 id="applet-properties-dialog"> 
+    <title>The Applet Properties Dialog</title>
+    <para>
+     Many applets have customizable properties.  These applets will
+     have a <guimenuitem>Properties...</guimenuitem> menu item in their
+     right-click <guimenu>pop-up menu</guimenu> which brings up the
+     <interface>Properties</interface> dialog where you can alter the 
+     appearance or behaviour of the applet.
+     <figure id="example-props-dialog-fig">
+      <title>An Example Applet Properties Dialog</title>
+      <screenshot>
+       <screeninfo>An Example Applets Properties Dialog</screeninfo>
+       <graphic fileref="applet_props_dialog" format="png"
+        srccredit="muet">
+       </graphic>
+      </screenshot>
+     </figure>
+     All <interface>Properties</interface> dialogs have the following
+     buttons at the bottom of the dialog:
+     <itemizedlist>
+      <listitem>
+       <para>
+        <guibutton>OK</guibutton> &mdash;
+        Pressing <guibutton>OK</guibutton> will activate any changes
+        in the properties you have made and close the
+        <interface>Properties</interface> dialog.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <guibutton>Apply</guibutton> &mdash;
+        Pressing <guibutton>Apply</guibutton> at any time will
+        make your changes active without closing the
+        <interface>Properties</interface> 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.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <guibutton>Close</guibutton> &mdash;
+        Pressing <guibutton>Close</guibutton> will close the
+        <interface>Properties</interface> dialog.  Only changes in the
+        configuration which were previously applied with the
+        <guibutton>Apply</guibutton> button will persist.  Other
+        changes will not be made active.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <guibutton>Help</guibutton> &mdash;
+        Pressing <guibutton>Help</guibutton> brings up the manual for
+        the application, opening it to the page describing the
+        <interface>Properties</interface> dialog.
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+   </sect2>
+ 
+   <sect2 id="common-right-click-items"> 
+    <title>Other Common Pop-Up Items</title>
+    <para>
+     Many applets also have one or more of the following items in their
+     right-click pop-up menu:
+     <variablelist>
+      <varlistentry>
+       <term>Run...</term>
+       <listitem>
+        <para>
+         The <guimenuitem>Run...</guimenuitem> 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: 
+        </para>
+        <orderedlist>
+         <listitem>
+          <para>
+           The <application>CPU Load</application> applet, which monitors
+           what programs are running, has a <guimenuitem>Run
+           gtop...</guimenuitem>  menu item. Selecting this menu item
+           starts <application>GTop</application>, which allows you to
+           view and control programs which are running.
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           The <application>CD Player</application> applet has a
+           <guimenuitem>Run gtcd...</guimenuitem> menu item which
+           starts the GNOME <application>CD Player</application> when
+           selected, which has more capabilities than the applet.
+          </para>
+         </listitem>
+        </orderedlist>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
+   </sect2>
+  </sect1>
+  
+  <sect1 id="feedback">
+   <title>Feedback</title>
+   <sect2 id="reporting-bugs"> 
+    <title>Reporting Applet Bugs</title>
+    <para>
+     GNOME users are encouraged to report bugs to <ulink type="http"
+     url="http://bugs.gnome.org">The GNOME Bug Tracking
+     System</ulink>.  The easiest way to submit bugs is to use the
+     <application>Bug Report Tool</application> program by selecting
+     <menuchoice>
+      <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+      <guimenuitem>Bug Report Tool</guimenuitem> 
+     </menuchoice>.
+     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.
+    </para>
+   </sect2>
+   <sect2 id="documentation-feedback"> 
+    <title>Providing Feedback</title>
+    <para>
+     GNOME users are welcome to provide suggestions for how
+     applications and documentation can be improved.  Suggestions for
+     application changes should be submitted using the
+     <application>Bug Report Tool</application> 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
+     <email>docs@gnome.org</email>. 
+    </para>
+   </sect2>
+   <sect2 id="joining-gnome">  
+    <title>Joining GNOME</title>
+    <para>
+     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 &mdash; <ulink type="http"
+     url="http://developer.gnome.org">The GNOME Development
+     Site</ulink>, documentation writers &mdash; <ulink type="http"
+     url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
+     Project</ulink>, icon design artists &mdash; <ulink type="http"
+     url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
+     general &mdash; <ulink type="http"
+     url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
+     or just join the gnome-list email list (see <ulink type="http"
+     url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
+     Lists</ulink>) to discuss what you are interested in doing.
+    </para>
+   </sect2>
+  </sect1>
+ </chapter>
+
+ <!-- ############### Template Applets ##################### -->
+ <chapter id="template-applets">
+  <title>Template Applets</title>
+
+  &TEMPLATE-APPLET
+
+ </chapter>
+
+</book>
+
+
+
+
+
+
+
+
+
+ + 
+
+
+  <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
+  <!-- your applet. Most importantly, all id attributes should start -->
+  <!-- with the name of your applet - this is necessary to avoid name -->
+  <!-- conflict among different applets --> 
+  <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
+  <!-- Please replace HACKER-NAME with the applet author's name and -->
+  <!-- HACKER-EMAIL with the applet author's email -->
+
+  <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
+  <!-- Screenshots should be in PNG format and placed in the -->
+  <!-- same directory as GNOMEAPPLET-applet.sgml -->
+
+  <!-- Applet docs will be merged into <chapter>'s inside a -->
+  <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
+  <!-- correct.-->
+
+  <!-- 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 Foundation. -->
+
+  <!-- ###############   GNOMEAPPLET   ############### -->
+  <sect1 id="GNOMEAPPLET">
+   <title>GNOMEAPPLET Applet</title> 
+
+   <para> 
+    <application>GNOMEAPPLET</application> applet, shown in <xref
+    linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
+    add this applet to a <interface>Panel</interface>, see <xref
+    linkend="adding-applets">. 
+   </para>
+  
+ 
+   <figure id="GNOMEAPPLET-fig">
+   <title>GNOMEAPPLET</title>
+   <screenshot>
+    <screeninfo>GNOMEAPPLET</screeninfo>
+    <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
+    </graphic>
+   </screenshot>
+   </figure>
+
+   <sect2 id="GNOMEAPPLET-usage">
+    <title>Usage</title>
+    <para>
+     This applet does nothing. To use it, just
+     left-click on it and it will instantly do nothing.   
+    </para>
+   </sect2>
+
+   <sect2 id="GNOMEAPPLET-right-click">
+    <title>Right-Click Pop-Up Menu Items</title>
+    <para> 
+     In addition to the standard menu items (see <xref
+     linkend="standard-right-click-items">), the right-click pop-up menu has 
+     the following items: 
+     <itemizedlist> 	
+      <listitem>
+       <para>
+        <guimenuitem>Properties...</guimenuitem> &mdash; This menu
+        item opens the <interface>Properties</interface> dialog (see
+        <xref linkend="GNOMEAPPLET-properties">) which allows you to
+        customize the appearance and behavior of this applet.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <guimenuitem>Run Hello World...</guimenuitem> &mdash; This
+        menu item starts the program <application>Hello
+        World</application>, used to say "hello" to the world. 
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+   </sect2>
+
+   <sect2 id="GNOMEAPPLET-properties">
+    <title>Properties</title>
+    <para>
+     You can configure <application>GNOMEAPPLET</application> applet by
+     right-clicking on the applet and choosing the
+     <guimenuitem>Properties...</guimenuitem> menu item. This will open the
+     <interface>Properties</interface> dialog, shown in <xref
+     linkend="GNOMEAPPLET-properties-fig">.
+    </para>
+    <figure id="GNOMEAPPLET-properties-fig">
+     <title>Properties Dialog</title>
+     <screenshot>
+      <screeninfo>Properties Dialog</screeninfo> 
+      <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
+      </graphic>
+     </screenshot>
+    </figure>
+    
+    <para> 
+     To change the color of the applet, click on the
+     <guibutton>color</guibutton> button. To change other properties,
+     click on other buttons. 
+    </para>
+
+    <para>
+     For more information on the <interface>Properties</interface>
+     dialog, including descriptions of the <guibutton>OK</guibutton>,
+     <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
+     <guibutton>Help</guibutton> buttons, see <xref
+     linkend="applet-properties-dialog">.
+    </para>
+   </sect2>
+  
+   <sect2 id="GNOMEAPPLET-bugs">
+    <title> Known Bugs and Limitations</title>
+    <para>
+     There are no known bugs in the
+     <application>GNOMEAPPLET</application> applet. 
+    </para>
+   </sect2>
+
+   <sect2 id="GNOMEAPPLET-authors">
+    <title>Authors</title>
+    <para>
+     This applet was writen by HACKER-NAME
+     <email>HACKER-EMAIL</email>.  The documentation for this applet
+     which you are reading now was written by
+     YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
+     bug reports and suggestions for improvements, see <xref
+     linkend="feedback">. 
+    </para>
+   </sect2>
+
+  </sect1>
+
+
+
+
+
+
+
+
+
+

+
+
+
+ + + + + + + + + + + +
+Prev Home 
Template 2: Applet Manual For GNOME 1.x Up 
+
+ + diff --git a/tests/docbook/result/xtchunk/html/index.orig b/tests/docbook/result/xtchunk/html/index.orig new file mode 100644 index 0000000..b742bb2 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/index.orig @@ -0,0 +1,373 @@ + + + + +The GNOME Handbook of Writing Software Documentation + + + + + +
+ + + + + + + +
The GNOME Handbook of Writing Software Documentation
   Next +
+
+
+
+
+

+The GNOME Handbook of Writing Software Documentation

+
+

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! +

+

Copyright © 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. +

+
+
+ + + + + +
Revision History
Revision + 0.99 + + 04.10.2000 +
+
+
+
+

Table of Contents

+
+
Introduction +
+
+
The GNOME Documentation Project +
+
Notation and Conventions +
+
About This Handbook +
+
+
Getting Started Writing GNOME Documentation +
+
+
Selecting A Document +
+
Installing and Using DocBook +
+
GDP Document Templates +
+
Screenshots +
+
Application Bugs +
+
Using CVS +
+
+
The GNOME Documentation System +
+
+
The GNOME Help Browser +
+
The GNOME Help Browser (GNOME-2.0) +
+
Dynamic Document Synthesis(GNOME-2.0) +
+
The GNOME Documentation Components +
+
+
DocBook Basics +
+
+
Introduction to DocBook +
+
XML and SGML +
+
Structure Elements +
+
Inline Elements +
+
+
GDP Documentation Conventions +
+
+
Conventions for All GDP Documentation +
+
Conventions for Application Documentation +
+
+
Writing Application and Applet Manuals +
+
Listing Documents in the Help Menu +
+
Application Help Buttons +
+
Packaging Applet Documentation +
+
+
Applet Documentation Files +
+
Adding Documentation to an Applet Menu +
+
+
Writing Context Sensitive Help (coming in GNOME-2.0) +
+
Referring to Other GNOME Documentation (coming in + GNOME-2.0) +
+
Basics of Documentation Style +
+
+
Planning +
+
Achieving a Balanced Style +
+
Structure +
+
Grammar and Spelling +
+
+
Teamwork +
+
+
Working With The GDP Team +
+
Working With Developers +
+
+
Finishing A Document +
+
+
Editing The Document +
+
Submitting The Document +
+
+
Resources +
+
+
Resources On The Web +
+
Books +
+
Mailing Lists +
+
IRC +
+
+
A Document Templates +
+
+
Template 1: Application Manual +
+
Template 2: Applet Manual For GNOME 1.x +
+
Template 2: Applet Manual For GNOME 2.x +
+
+
+
+
+

+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 the section called “Getting Started Writing GNOME Documentation”, 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 CodeProgram 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. +

+
+
+
+
+
+ + + + + + + + + + + +
   Next +
   Getting Started Writing GNOME Documentation
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs02.orig b/tests/docbook/result/xtchunk/html/indexs02.orig new file mode 100644 index 0000000..ca6c50f --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs02.orig @@ -0,0 +1,635 @@ + + + + +Getting Started Writing GNOME Documentation + + + + + + + +
+ + + + + + + +
Getting Started Writing GNOME Documentation
+Prev   Next +
+
+
+
+

+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: + 

+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+
+

+

+ Books: + 

+<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+
+

+
+
+

+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 the section called “Installing DocBook”. +

+
+
+

+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 the section called “GDP Stylesheets”. +

+
+
+
+

+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: +

+
+
+<figure>
+ <title>My Image</title>
+ <screenshot>
+  <screeninfo>Sample GNOME Display</screeninfo>
+  <graphic  format="png" fileref="myfile" srccredit="me">
+  </graphic>
+ </screenshot>
+</figure>
+
+

+ 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: +

+
+

+ 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 + Appendix A. Document Templates. 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 the section called “GDP DTD (PNG Image Support)” 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 the section called “Images in DocBook Tools” 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 the section called “Creating Something Useful with your Docs”), 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 the section called “Images in DocBook Tools”, 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 -e 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. +

+
+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
The GNOME Handbook of Writing Software Documentation Up The GNOME Documentation System
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs03.orig b/tests/docbook/result/xtchunk/html/indexs03.orig new file mode 100644 index 0000000..33ce5b0 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs03.orig @@ -0,0 +1,207 @@ + + + + +The GNOME Documentation System + + + + + + + +
+ + + + + + + +
The GNOME Documentation System
+Prev   Next +
+
+
+
+

+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 the section called “Writing Application and Applet Manuals” 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 the section called “Application Help Buttons” 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 the section called “Writing Context Sensitive Help (coming in GNOME-2.0)” + 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. +

+
+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Getting Started Writing GNOME Documentation Up DocBook Basics
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs04.orig b/tests/docbook/result/xtchunk/html/indexs04.orig new file mode 100644 index 0000000..9c3df4e --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs04.orig @@ -0,0 +1,756 @@ + + + + +DocBook Basics + + + + + + + +
+ + + + + + + +
DocBook Basics
+Prev   Next +
+
+
+
+

+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 section called “Installing DocBook”. +

+

+ 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 section called “GDP Stylesheets”. +

+

+ 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 section called “Resources”. The following sections also provide + convenient instructions on which markup tags to use in various + circumstances. Be sure to read the section called “GDP Documentation Conventions ” + 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>
+ <title>TIP</title>
+ <para>
+  To speed up program compilation, use <application>gcc</application>
+  compiler with Pentium optimization.
+ </para>
+</tip>
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: + + 

+
+<figure id="shot1">
+ <title>Screenshot</title>
+ <screenshot>
+  <screeninfo>Screenshot of a program</screeninfo>
+  <graphic format="PNG"  fileref="figures/example_screenshot" srccredit="ME">
+  </graphic>
+ </screenshot>
+</figure>
+
+ replacing example_screenshot with the + actual file name (without extension). The result will look like this: + +
+

+Figure 1. Screenshot +

+

+
+

+
+

+NOTE

+

+ Notice in this example that the screenshot file name does + not include the file type extension -- to find out + why, please read the section called “Images in DocBook Tools”. +

+
+
+
+

+Program listings and terminal session

+

+ To show a file fragment--for example, program + listing--use <programlisting> tag: + 

+
+<programlisting>
+[Desktop Entry] 
+Name=Gnumeric spreadsheet
+Exec=gnumeric 
+Icon=gnome-gnumeric.png 
+Terminal=0
+Type=Application
+</programlisting>
+
+ 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: + 

+
+<screen>
+<prompt>bash$</prompt><userinput>make love</userinput> 
+make: *** No rule to make target `love'. Stop.
+</screen>
+
+ 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: + 

+
+<itemizedlist>
+  <listitem>
+    <para>
+      <guilabel>Show backup files</guilabel> &mdash; This will
+      show any backup file that might be on your system.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <guilabel>Show hidden files</guilabel> &mdash; This will
+      show all "dot files" or files that begin with a dot.  This
+      files typically include configuration files and directories.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <guilabel>Mix files and directories</guilabel> &mdash; This
+      option will  display files and directories in the order you
+      sort them instead of 
+      always having directories shown above files.
+    </para>
+   </listitem>
+</itemizedlist> 
+
+
+ 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 the section called “ Special symbols ”). 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: + 

+
+<variablelist>
+  <varlistentry>
+    <term> <sgmltag>&lt;itemizedlist></sgmltag></term> 
+    <listitem><para> 
+	This is the simplest unnumbered list, parallel to
+        <sgmltag>&lt;ul></sgmltag> in HTML. Here is an example:...
+    </para></listitem>
+    </varlistentry>
+    <varlistentry>		 
+	<term> <sgmltag>&lt;orderedlist></sgmltag></term>
+     <listitem><para>	
+	This list is completely analogous to
+	<sgmltag>&lt;itemizedlist></sgmltag> 
+    </para></listitem>
+    </varlistentry>
+    <varlistentry>		 
+	<term> <sgmltag>&lt;variablelist></sgmltag></term>
+     <listitem><para>	
+		This list is used when each entry is rather long,...
+    </para></listitem>
+    </varlistentry>
+</variablelist>        
+
+
+

+
+

+ 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 + <guisubmenu>Utilities</guisubmenu> submenu of the + <guimenu>Main Menu</guimenu> +

    • +

  • + + <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: + 

+
+<menuchoice>
+ <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+ <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
+
+

+
+
+

+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: + 

+An example of a <link linkend="extip">tip</link> was given in
+<xref linkend="notes" />.  
+
+ which produces: An example of a tip was given in the section called “Notes, Warnings, And Tips”. +

+

+ Here notes and extip + are the id attributes of the section called “Notes, Warnings, And Tips” 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: + 

+ To find more about GNOME, please visit <ulink type="http"
+url="http://www.gnome.org">GNOME Web page</ulink> 
+
+ 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: + 

+
+<keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>Alt</keycap>
+ <keycap>F1</keycap>
+</keycombo>
+
+

+

+ Finally, if you want to show a shortcut for some menu + command, here are the appropriate tags (rather long): + 

+
+<menuchoice>
+ <shortcut>
+  <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
+ </shortcut> 
+ <guimenuitem> Quit</guimenuitem> 
+</menuchoice>
+
+ which produces simply + Quit (Ctrl-q) +

+
+
+

+E-mail addresses

+

To mark up e-mail + address, use <email>: + 

+ The easiest way to get in touch with me is by e-mail
+(<email>me@mydomain.com</email>)
+
+ 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. +

+
+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
The GNOME Documentation System Up GDP Documentation Conventions
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs05.orig b/tests/docbook/result/xtchunk/html/indexs05.orig new file mode 100644 index 0000000..424c7d3 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs05.orig @@ -0,0 +1,124 @@ + + + + +GDP Documentation Conventions + + + + + + + +
+ + + + + + + +
GDP Documentation Conventions
+Prev   Next +
+
+
+
+

+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 + the section called “XML and SGML” 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: + 

+
+<sect1 id="intro">
+ <title>Introduction</title>
+ <para>
+  blah-blah-blah This document describes version 1.0.53 of gfoo.
+ </para>
+</sect1>
+
+

+
+
+

+ 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). +

+
+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
DocBook Basics  Up Writing Application and Applet Manuals
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs06.orig b/tests/docbook/result/xtchunk/html/indexs06.orig new file mode 100644 index 0000000..61351fe --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs06.orig @@ -0,0 +1,108 @@ + + + + +Writing Application and Applet Manuals + + + + + + + +
+ + + + + + + +
Writing Application and Applet Manuals
+Prev   Next +
+
+
+
+

+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 + the section called “Template 1: Application Manual”. Applet manuals should be based on + the templates in the section called “Template 2: Applet Manual For GNOME 1.x” for GNOME + versions 1.x and the templates in the section called “Template 2: Applet Manual For GNOME 2.x” + 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 the section called “Listing Documents in the Help Menu”. + Applets should make their manuals available by + right-clicking on the applet. +

+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
GDP Documentation Conventions  Up Listing Documents in the Help Menu
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs07.orig b/tests/docbook/result/xtchunk/html/indexs07.orig new file mode 100644 index 0000000..c06f34d --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs07.orig @@ -0,0 +1,118 @@ + + + + +Listing Documents in the Help Menu + + + + + + + +
+ + + + + + + +
Listing Documents in the Help Menu
+Prev   Next +
+
+
+
+

+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. +

+
+

+Note

+

+ 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. +

+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Writing Application and Applet Manuals Up Application Help Buttons
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs08.orig b/tests/docbook/result/xtchunk/html/indexs08.orig new file mode 100644 index 0000000..9625da9 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs08.orig @@ -0,0 +1,89 @@ + + + + +Application Help Buttons + + + + + + + +
+ + + + + + + +
Application Help Buttons
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Listing Documents in the Help Menu Up Packaging Applet Documentation
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs09.orig b/tests/docbook/result/xtchunk/html/indexs09.orig new file mode 100644 index 0000000..33a93c9 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs09.orig @@ -0,0 +1,140 @@ + + + + +Packaging Applet Documentation + + + + + + + +
+ + + + + + + +
Packaging Applet Documentation
+Prev   Next +
+
+
+
+

+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 the section called “Application Help Buttons”. +

+

+ 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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Application Help Buttons Up Writing Context Sensitive Help (coming in GNOME-2.0)
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs10.orig b/tests/docbook/result/xtchunk/html/indexs10.orig new file mode 100644 index 0000000..9a5ce56 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs10.orig @@ -0,0 +1,84 @@ + + + + +Writing Context Sensitive Help (coming in GNOME-2.0) + + + + + + + +
+ + + + + + + +
Writing Context Sensitive Help (coming in GNOME-2.0)
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Packaging Applet Documentation Up Referring to Other GNOME Documentation (coming in + GNOME-2.0)
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs11.orig b/tests/docbook/result/xtchunk/html/indexs11.orig new file mode 100644 index 0000000..2d0cb85 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs11.orig @@ -0,0 +1,56 @@ + + + + +Referring to Other GNOME Documentation (coming in + GNOME-2.0) + + + + + + + +
+ + + + + + + +
Referring to Other GNOME Documentation (coming in + GNOME-2.0)
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Writing Context Sensitive Help (coming in GNOME-2.0) Up Basics of Documentation Style
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs12.orig b/tests/docbook/result/xtchunk/html/indexs12.orig new file mode 100644 index 0000000..ef935a9 --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs12.orig @@ -0,0 +1,200 @@ + + + + +Basics of Documentation Style + + + + + + + +
+ + + + + + + +
Basics of Documentation Style
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Referring to Other GNOME Documentation (coming in + GNOME-2.0) Up Teamwork
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs13.orig b/tests/docbook/result/xtchunk/html/indexs13.orig new file mode 100644 index 0000000..f17784e --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs13.orig @@ -0,0 +1,90 @@ + + + + +Teamwork + + + + + + + +
+ + + + + + + +
Teamwork
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Basics of Documentation Style Up Finishing A Document
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs14.orig b/tests/docbook/result/xtchunk/html/indexs14.orig new file mode 100644 index 0000000..4332d0d --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs14.orig @@ -0,0 +1,81 @@ + + + + +Finishing A Document + + + + + + + +
+ + + + + + + +
Finishing A Document
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Teamwork Up Resources
+
+ + diff --git a/tests/docbook/result/xtchunk/html/indexs15.orig b/tests/docbook/result/xtchunk/html/indexs15.orig new file mode 100644 index 0000000..4be0f2c --- /dev/null +++ b/tests/docbook/result/xtchunk/html/indexs15.orig @@ -0,0 +1,98 @@ + + + + +Resources + + + + + + + +
+ + + + + + + +
Resources
+Prev   Next +
+
+
+
+

+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. +

+
+
+
+
+ + + + + + + + + + + +
+Prev Home Next +
Finishing A Document Up A. Document Templates
+
+ + diff --git a/tests/multiple/Makefile.am b/tests/multiple/Makefile.am index bd7437f..9136499 100644 --- a/tests/multiple/Makefile.am +++ b/tests/multiple/Makefile.am @@ -4,19 +4,29 @@ $(top_builddir)/libxslt/xsltproc: @(cd ../../libxslt ; make xsltproc) EXTRA_DIST = dict.dtd dict.xml dict.xsl result.xml \ - out/lettera.html out/lettera.orig out/letterb.html out/letterb.orig \ - out/letterc.html out/letterc.orig out/letterd.html out/letterd.orig \ - out/lettere.html out/lettere.orig out/letterf.html out/letterf.orig \ - out/letterg.html out/letterg.orig out/letterh.html out/letterh.orig \ - out/letterij.html out/letterij.orig out/letterk.html out/letterk.orig \ - out/letterl.html out/letterl.orig out/letterm.html out/letterm.orig \ - out/lettern.html out/lettern.orig out/lettero.html out/lettero.orig \ - out/letterp.html out/letterp.orig out/letterq.html out/letterq.orig \ - out/letterr.html out/letterr.orig out/letters.html out/letters.orig \ - out/lettert.html out/lettert.orig out/letteruv.html out/letteruv.orig \ - out/letterw.html out/letterw.orig out/letterx.html out/letterx.orig \ - out/lettery.html out/lettery.orig out/letterz.html out/letterz.orig \ - out/titlepage.html out/titlepage.orig + out/lettera.orig out/letterb.orig \ + out/letterc.orig out/letterd.orig \ + out/lettere.orig out/letterf.orig \ + out/letterg.orig out/letterh.orig \ + out/letterij.orig out/letterk.orig \ + out/letterl.orig out/letterm.orig \ + out/lettern.orig out/lettero.orig \ + out/letterp.orig out/letterq.orig \ + out/letterr.orig out/letters.orig \ + out/lettert.orig out/letteruv.orig \ + out/letterw.orig out/letterx.orig \ + out/lettery.orig out/letterz.orig \ + out/titlepage.orig + + +GENERATED = \ + out/lettera.html out/letterb.html out/letterc.html out/letterd.html \ + out/lettere.html out/letterf.html out/letterg.html out/letterh.html \ + out/letterij.html out/letterk.html out/letterl.html out/letterm.html \ + out/lettern.html out/lettero.html out/letterp.html out/letterq.html \ + out/letterr.html out/letters.html out/lettert.html out/letteruv.html \ + out/letterw.html out/letterx.html out/lettery.html out/letterz.html \ + out/titlepage.html all: test @@ -24,10 +34,14 @@ test tests: $(top_builddir)/libxslt/xsltproc @(echo > .memdump) @($(top_builddir)/libxslt/xsltproc $(srcdir)/dict.xsl $(srcdir)/dict.xml > dict.res ; \ diff $(srcdir)/result.xml dict.res; \ - for i in $(srcdir)/out/letter*.orig ; do \ - diff $$i $(srcdir)/out/`basename $$i .orig`.html; done ; \ - diff $(srcdir)/out/titlepage.orig $(srcdir)/out/titlepage.html; \ + for i in $(srcdir)/out/letter*.html $(srcdir)/out/titlepage.html ; do \ + orig=$(srcdir)/out/`basename $$i .html`.orig ; \ + if [ -f $$orig ] ; then \ + diff $$orig $$i ; \ + else \ + echo "new $$orig" ; cp $$i $$orig ; \ + fi ; done ; \ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" || true;\ - rm -f dict.res) + rm -f dict.res $(GENERATED)) diff --git a/tests/multiple/out/lettera.orig b/tests/multiple/out/lettera.orig index efbb37d..2e36c43 100644 --- a/tests/multiple/out/lettera.orig +++ b/tests/multiple/out/lettera.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterb.orig b/tests/multiple/out/letterb.orig index 0257731..aa71a28 100644 --- a/tests/multiple/out/letterb.orig +++ b/tests/multiple/out/letterb.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterc.orig b/tests/multiple/out/letterc.orig index 3666c8f..ab4c2c8 100644 --- a/tests/multiple/out/letterc.orig +++ b/tests/multiple/out/letterc.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterd.orig b/tests/multiple/out/letterd.orig index 922912c..630d05f 100644 --- a/tests/multiple/out/letterd.orig +++ b/tests/multiple/out/letterd.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/lettere.orig b/tests/multiple/out/lettere.orig index cdc5cc0..4c4ea1d 100644 --- a/tests/multiple/out/lettere.orig +++ b/tests/multiple/out/lettere.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterf.orig b/tests/multiple/out/letterf.orig index f6964b0..c36fc94 100644 --- a/tests/multiple/out/letterf.orig +++ b/tests/multiple/out/letterf.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterg.orig b/tests/multiple/out/letterg.orig index e7035d7..057e0c7 100644 --- a/tests/multiple/out/letterg.orig +++ b/tests/multiple/out/letterg.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterh.orig b/tests/multiple/out/letterh.orig index 64fd55c..a1aabe9 100644 --- a/tests/multiple/out/letterh.orig +++ b/tests/multiple/out/letterh.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterij.orig b/tests/multiple/out/letterij.orig index d7f5f63..5766316 100644 --- a/tests/multiple/out/letterij.orig +++ b/tests/multiple/out/letterij.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterk.orig b/tests/multiple/out/letterk.orig index 0ae0327..85b88bc 100644 --- a/tests/multiple/out/letterk.orig +++ b/tests/multiple/out/letterk.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterl.orig b/tests/multiple/out/letterl.orig index b7d4a1a..3c4e9a7 100644 --- a/tests/multiple/out/letterl.orig +++ b/tests/multiple/out/letterl.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterm.orig b/tests/multiple/out/letterm.orig index 89fb11a..ce4ee88 100644 --- a/tests/multiple/out/letterm.orig +++ b/tests/multiple/out/letterm.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/lettern.orig b/tests/multiple/out/lettern.orig index b771eb3..3ad7e98 100644 --- a/tests/multiple/out/lettern.orig +++ b/tests/multiple/out/lettern.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/lettero.orig b/tests/multiple/out/lettero.orig index caf4b9f..a85124f 100644 --- a/tests/multiple/out/lettero.orig +++ b/tests/multiple/out/lettero.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterp.orig b/tests/multiple/out/letterp.orig index 4829290..3809c0e 100644 --- a/tests/multiple/out/letterp.orig +++ b/tests/multiple/out/letterp.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterq.orig b/tests/multiple/out/letterq.orig index f7525db..a34a5dc 100644 --- a/tests/multiple/out/letterq.orig +++ b/tests/multiple/out/letterq.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterr.orig b/tests/multiple/out/letterr.orig index 73aa7f1..b7bdb6b 100644 --- a/tests/multiple/out/letterr.orig +++ b/tests/multiple/out/letterr.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letters.orig b/tests/multiple/out/letters.orig index dabf605..819308b 100644 --- a/tests/multiple/out/letters.orig +++ b/tests/multiple/out/letters.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/lettert.orig b/tests/multiple/out/lettert.orig index 0f3aff6..bfe0887 100644 --- a/tests/multiple/out/lettert.orig +++ b/tests/multiple/out/lettert.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letteruv.orig b/tests/multiple/out/letteruv.orig index 8e2af18..fa91d9d 100644 --- a/tests/multiple/out/letteruv.orig +++ b/tests/multiple/out/letteruv.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterw.orig b/tests/multiple/out/letterw.orig index 5b806f4..dfaf933 100644 --- a/tests/multiple/out/letterw.orig +++ b/tests/multiple/out/letterw.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterx.orig b/tests/multiple/out/letterx.orig index bb3d524..ecfac33 100644 --- a/tests/multiple/out/letterx.orig +++ b/tests/multiple/out/letterx.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/lettery.orig b/tests/multiple/out/lettery.orig index 3dd0e1f..85d1bd5 100644 --- a/tests/multiple/out/lettery.orig +++ b/tests/multiple/out/lettery.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/letterz.orig b/tests/multiple/out/letterz.orig index 363d4ea..8073d86 100644 --- a/tests/multiple/out/letterz.orig +++ b/tests/multiple/out/letterz.orig @@ -1,3 +1,4 @@ + diff --git a/tests/multiple/out/titlepage.orig b/tests/multiple/out/titlepage.orig index 3e44987..a3a347c 100644 --- a/tests/multiple/out/titlepage.orig +++ b/tests/multiple/out/titlepage.orig @@ -1,3 +1,4 @@ +