{"id":20079527,"url":"https://github.com/transpect/xml2tex","last_synced_at":"2025-05-05T23:30:26.704Z","repository":{"id":30367525,"uuid":"33920078","full_name":"transpect/xml2tex","owner":"transpect","description":"Converts XML to LaTeX","archived":false,"fork":false,"pushed_at":"2025-03-31T13:22:29.000Z","size":589,"stargazers_count":46,"open_issues_count":4,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-09T05:41:32.798Z","etag":null,"topics":["latex","mathml","tabular"],"latest_commit_sha":null,"homepage":null,"language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transpect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-14T08:32:04.000Z","updated_at":"2025-04-03T06:46:36.000Z","dependencies_parsed_at":"2023-11-24T16:24:54.746Z","dependency_job_id":"1ef30ccb-4f5e-4253-b7ad-b9496fa6d664","html_url":"https://github.com/transpect/xml2tex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transpect%2Fxml2tex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transpect%2Fxml2tex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transpect%2Fxml2tex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transpect%2Fxml2tex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transpect","download_url":"https://codeload.github.com/transpect/xml2tex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252592752,"owners_count":21773327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["latex","mathml","tabular"],"created_at":"2024-11-13T15:23:15.611Z","updated_at":"2025-05-05T23:30:26.373Z","avatar_url":"https://github.com/transpect.png","language":"XSLT","readme":"# xml2tex\n\nA library for converting arbitrary XML to TeX.\n\n## setup and run xml2tex\n\nxml2tex is not a standalone tool but an XProc library which also depends on other modules.\nSo you need a little setup to run it. First start with creating a project directory and \ncloning the modules from GitHub:\n\n```\n$ mkdir asyoulike \u0026\u0026 cd asyoulike\n$ git clone --recursive -b saxon98 https://github.com/transpect/calabash-frontend.git calabash\n$ git clone https://github.com/transpect/mml2tex.git\n$ git clone https://github.com/transpect/cascade.git\n$ git clone https://github.com/transpect/mml-normalize.git\n$ git clone https://github.com/transpect/xproc-util.git\n$ git clone https://github.com/transpect/xslt-util.git\n$ git clone https://github.com/transpect/xml2tex.git\n```\n\nNow we add an XML catalog to resolve the import URIs of the XProc modules.\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003ccatalog xmlns=\"urn:oasis:names:tc:entity:xmlns:xml:catalog\"\u003e\n  \u003cnextCatalog catalog=\"../mml2tex/xmlcatalog/catalog.xml\"/\u003e\n  \u003cnextCatalog catalog=\"../mml-normalize/xmlcatalog/catalog.xml\"/\u003e\n  \u003cnextCatalog catalog=\"../xproc-util/xmlcatalog/catalog.xml\"/\u003e\n  \u003cnextCatalog catalog=\"../xslt-util/xmlcatalog/catalog.xml\"/\u003e  \n  \u003cnextCatalog catalog=\"../xml2tex/xmlcatalog/catalog.xml\"/\u003e\n  \u003cnextCatalog catalog=\"../cascade/xmlcatalog/catalog.xml\"/\u003e\n\u003c/catalog\u003e\n```\n\nStore this XML catalog file to `xmlcatalog/catalog.xml`.\n\nNow you just have to run calabash.\n\n```\n$ calabash/calabash.sh -i source=xml2tex/example/example.xml -i conf=xml2tex/example/conf-hubcssa.xml xml2tex/xpl/xml2tex.xpl\n```\n\nAlternatively, you can download a [release of docx2tex](https://github.com/transpect/docx2tex/releases) that uses this xml2tex library,\nor you can clone docx2tex recursively for the most current libraries.\nThere, all the repos listed above are already included as submodules, and the XML Catalog is also present.\n\n## Configuration\n\nxml2tex can be configured for any kind of XML format.\nA sample XML configuration file is stored in the `example` directory.\n\nA [RelaxNG schema](https://raw.githubusercontent.com/transpect/xml2tex/master/schema/xml2tex.rng) \nis located in the `schema` directory. You can use\nthe schema to check if your configuration file is valid and some editors which \nsupport RelaxNG will provide code completion and tool tips.\n\nHere is an example for a very basic configuration:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c?xml-model href=\"../schema/xml2tex.rng\" type=\"application/xml\" schematypens=\"http://relaxng.org/ns/structure/1.0\"?\u003e\n\u003c?xml-model href=\"../schema/xml2tex.rng\" type=\"application/xml\" schematypens=\"http://purl.oclc.org/dsdl/schematron\"?\u003e\n\u003cset xmlns=\"http://transpect.io/xml2tex\"\u003e\n\n  \u003cns prefix=\"dbk\" uri=\"http://docbook.org/ns/docbook\"/\u003e\n\n  \u003cpreamble\u003e\n    \\documentclass{scrbook}\n    \\usepackage{graphicx}\n    \\usepackage{hyperref}\n    \\usepackage{multirow}\n  \u003c/preamble\u003e\n\n  \u003cfront\u003e\n    \\maketitle\n  \u003c/front\u003e\n\n  \u003cback\u003e\n    \\printindex\n  \u003c/back\u003e\n\n  \u003ctemplate context=\"dbk:para[not(parent::dbk:entry)][not(parent::dbk:footnote)]\"\u003e\n    \u003crule break-after=\"2\"\u003e\n      \u003ctext/\u003e\n    \u003c/rule\u003e\n  \u003c/template\u003e\n\n  \u003ctemplate context=\"dbk:para[@role eq 'Zitat']\"\u003e\n    \u003crule type=\"env\" name=\"quote\"\u003e\n      \u003ctext/\u003e\n    \u003c/rule\u003e\n  \u003c/template\u003e\n  \n  \u003ccharmap\u003e\n    \u003cchar character=\"\u0026#xad;\" string=\"\u0026quot;-\"/\u003e\n    \u003cchar character=\"Ä\" string=\"\\\u0026#34;A\" context=\"dbk:phrase, dbk:section|dbk:para, dbk:entry\"/\u003e\n    \u003cchar character=\"ä\" string=\"\\\u0026#34;a\"/\u003e\n    \u003cchar character=\"Ö\" string=\"\\\u0026#34;O\"/\u003e\n    \u003cchar character=\"ö\" string=\"\\\u0026#34;o\" /\u003e\n    \u003cchar character=\"Ü\" string=\"\\\u0026#34;U\" /\u003e\n    \u003cchar character=\"ü\" string=\"\\\u0026#34;u\" /\u003e\n    \u003cchar character=\"ß\" string=\"\\ss{}\" /\u003e\n    \u003cchar character=\"…\" string=\"...\" /\u003e\n  \u003c/charmap\u003e\n\u003c/set\u003e\n```\n\n### Preamble\nThe LaTeX preamble is constructed with the `preamble` element. Enter static text such as document class name, package\ndeclarations and other stuff you may need.\n```xml\n\u003cpreamble\u003e\n    \\documentclass{scrbook}\n    \\usepackage{graphicx}\n    \\usepackage{hyperref}\n    \\usepackage{multirow}\n    \\usepackage{amsmath}\n    \\usepackage{amssymb}\n\u003c/preamble\u003e\n```\n\n### Frontmatter\n\nIf you want to put content after `\\begin{document}` but before the XML is inserted, you can do this with the `front` element.\nTypical use cases might be the creation of a frontmatter. If you do not want to add static content, you can help yourself\nwith a few bits of XSLT as shown below:\n\n```xml\n\u003cfront\u003e\n    \\title{\u003cxsl:value-of select=\"title\"/\u003e}\n    \\date{\u003cxsl:value-of select=\"info/date\"/\u003e}\n    \\author{\u003cxsl:value-of select=\"info/author\"/\u003e}\n\u003c/front\u003e\n```\n\n### Backmatter\n\nIf you want to put content right before `\\end{document}`, you can use the `back` element for this purpose.\n\n```xml\n\u003cback\u003e\n    \\printindex\n\u003c/back\u003e\n```\n\n### XML namespaces\n\nIf your XML input document use XML namespaces, it's necessary to declare each namespace with a corresponding `ns` element.\n```xml\n\u003cns prefix=\"dbk\" uri=\"http://docbook.org/ns/docbook\"/\u003e\n\u003cns prefix=\"css\" uri=\"http://www.w3.org/1996/css\"/\u003e\n```\nDon't forget to use the declared namespace prefixes in the XPath expression of the context attribute. If a template don't match the considered XML nodes, it could be caused by a wrong namespace. \n* wrong: `context=\"para\"`\n* right: `context=\"dbk:para\"`\n\n### Templates and Rules\n\n#### Templates\n\nTemplates are considered to match a certain XML node with a XPath expression and convert its contents according to a Rule statement into a LaTeX instruction. A template is specified with a `template` element.\n\n```xml\n\u003ctemplate context=\"dbk:para[@role = ('heading1')]\"\u003e\n    \u003crule type=\"cmd\" name=\"chapter\" break-after=\"1\"\u003e\n      \u003cparam/\u003e\n    \u003c/rule\u003e\n\u003c/template\u003e\n```\nThe `@context` attribute is used to specify the XML node which is processed by the template. \n\nA Template can contain zero or one `rule` child element. If no `rule` exists, the XML node specified by the  `@context` attribute is dropped.\n\nGiven this XML element…\n```xml\n\u003cpara xmlns=\"http://docbook.org/ns/docbook\" role=\"heading1\"\u003emy headline\u003c/para\u003e\n```\n…the template above would generate this LaTeX code:\n```xml\n\\chapter{my headline}\n```\n\n#### Rules\n\nA rule is declared as child element named `rule` and is used to specify the LaTeX instruction.\n\n```xml\n\u003crule type=\"cmd\" name=\"chapter\" break-after=\"1\"\u003e\n  \u003cparam/\u003e\n\u003c/rule\u003e\n```\n\nThe value of the `@type` attribute specifies the certain type of the LaTeX instruction. Permitted values are `cmd` for instructions such as `\\chapter` and `env` for environments such as `\\begin{itemize} … \\end{itemize}`.\n\nThe `@name` attribute describes the name of the LaTeX instruction.\n\n`@break-after` is used to control the line breaks after the element. This attribute is necessary to control the whitespace after regular paragraphs.\n\n#### Parameters, Options and Text\n\nA rule can contain three child elements: `text`, `param`, `option`, which define how the content of the current XML node is wrapped. The `param` element specifies that the contents of the current context XML node is wrapped with curly braces `{}`. `option` is used to wrap the content with brackets `[]`, hence `text` process it without any wrapper.\n\nEach of these elements can contain a `@select` attribute. This attribute is optional and can be used to specify an XML node within the current context. The example below shows how to use the `@select` attribute to construct the parameters of a LaTeX link instruction.\n\n```xml\n\u003ctemplate context=\"dbk:link\"\u003e\n  \u003crule type=\"cmd\" name=\"href\"\u003e\n    \u003cparam select=\"@xlink:href\"/\u003e\n    \u003cparam select=\"dbk:phrase\"/\u003e\n  \u003c/rule\u003e\n\u003c/template\u003e\n```\n\n### Storing separate files\n\nSome TeX packages rely on external configuration files. For this purpose,\nyou can store the evaluated context of a `template` to a separate file.\nThe following example shows briefly how to generate a separate BibTeX file\nfrom an XML bibliography.\n\n```xml\n\u003ctemplate context=\"dbk:bibliography[@role eq 'Citavi']\"\u003e\n  \u003cxsl:variable name=\"bibtex-path\" select=\"concat($path, '/', $basename, '-citavi.bib')\" as=\"xs:string\"/\u003e\n  \u003crule name=\"bibliography\" type=\"cmd\" break-after=\"2\" break-before=\"2\"\u003e\n    \u003cparam select=\"concat($basename, '-citavi')\"/\u003e\n  \u003c/rule\u003e\n  \u003cfile href=\"{$bibtex-path}\" encoding=\"utf-8\"/\u003e\n\u003c/template\u003e\n```\n\n### Style Mapping\n\nFrequently, you just want to map one element to a specific TeX instruction. Therefore xml2tex provides a simple `style` mapping.\nThe content is selected by a specific attribute value. Therefore, you have to declare the name of the attribute globally with\n`@style-attribute`. Within `style` you specify the attribute value with `@name`. With `@start` and `@end`, you define which text\nis put around the content. Note: use Unicode entities such as `\u0026#xa;` to insert line breaks or handle whitespace.\n\nIn the example below, all elements with a `@role` attribute and the value `heading1` are converted to `\\chapter{ … }`.\n\n```xml\n\u003cset xmlns=\"http://transpect.io/xml2tex\"\n  style-attribute=\"role\"\u003e\n\n  \u003cstyle name=\"heading1\" start=\"\\chapter{\" end=\"}\"/\u003e\n\n\u003c/set\u003e\n```\n\n### Regular Expressions\n\nInstead of templates and style mapping, you can also use regular expressions to construct a LaTeX instruction. Therefore, you can use the element `regex` and specify a regular expressions with the `@regex` attribute.\n\nIf you want to use groups in your matching pattern, you can specify the optional attribute`regex-group` to select a specific  group. The example below shows how to construct a date makro with regular expressions.\n```xml\n\u003cregex regex=\"(\\d{2})\\.(\\d{2})\\.(\\d{4})\"\u003e\n  \u003crule type=\"cmd\" name=\"date\"\u003e\n    \u003cparam regex-group=\"1\"/\u003e\n    \u003cparam regex-group=\"2\"/\u003e\n    \u003cparam regex-group=\"3\"/\u003e\n  \u003c/rule\u003e\n\u003c/regex\u003e\n```\n\nPlease note that you can restrict the scope of the regex with the optional `@context` attribute. To suppress Unicode normalization, you can also add the attribute `normalize-unicode` with the value `false`.\n\n### Character Maps\n\nSome LaTeX processors are only able to handle constrained character sets. Therefore it is recommended to include a character map in your configuration and map certain characters to LaTeX instructions. \n\nA character map is wrapped by a `charmap` element. It can contain multiple character mapping entries, each specified with a `char` element. The attribute `@character` contains the character to be replaced with the value of `@string`. An optional `@context` attribute can be used to restrict the replacement to a certain XML context.\n```xml\n\u003ccharmap\u003e\n  \u003cchar character=\"\u0026#xad;\" string=\"\u0026quot;-\"/\u003e\n  \u003cchar character=\"Ä\" string=\"\\\u0026#34;A\" context=\"dbk:phrase, dbk:section|dbk:para, dbk:entry\"/\u003e\n  \u003cchar character=\"ä\" string=\"\\\u0026#34;a\"/\u003e\n  \u003cchar character=\"Ö\" string=\"\\\u0026#34;O\"/\u003e\n  \u003cchar character=\"ö\" string=\"\\\u0026#34;o\" /\u003e\n  \u003cchar character=\"Ü\" string=\"\\\u0026#34;U\" /\u003e\n  \u003cchar character=\"ü\" string=\"\\\u0026#34;u\" /\u003e\n  \u003cchar character=\"ß\" string=\"\\ss{}\" /\u003e\n\u003c/charmap\u003e\n```\n\nPlease note: we use per default an irreversible unicode decomposition of diacritical characters to convert fractions or german Umlauts to\ntheir respective latex representations, e.g. `ü =\u003e \\\"u`. This unicode decomposition is just performed for characters which actually\ncan be decomposited into combining characters. For some languages e.g. with a kyrillic alphabet this can cause issues with TeX renderers who don't\nunderstand Unicode combining characters. There are two ways to suppress this Unicode normalization:\n\n#### 1. The sane way\n\nSelectively add characters which can be decomposited into a character and its respective combining character. Just add the character to the\n`charmap` and \"replace\" it with itself:\n\n```\n\u003ccharmap\u003e\n  \u003cchar character=\"ü\" string=\"ü\"/\u003e\n  \u003c!-- (...) --\u003e\n\u003c/charmap\u003e\n```\n\n#### 2. Your gun, your foot\n\nDeactivate character decomposition globally by just adding `decompose-diacritics=\"no\"` to the `xml2tex` root element.\n\n```\n\u003cset xmlns=\"http://transpect.io/xml2tex\" decompose-diacritics=\"no\"\u003e\n  \u003c!-- (...) --\u003e\n\u003c/set\u003e\n```\n\n### Import other configurations\n\nIn most cases it's more applicable to import an existing configuration than to write a new one from scratch or fork an existing one. There is a convenient method for importing other configurations. You just have to add at the top of your configuration an import statement which points to the location of the imported configuration. Here is an example:\n\n\n```xml\n\u003cset xmlns=\"http://transpect.io/xml2tex\"\u003e\n\n  \u003cimport href=\"../conf/default.xml\"/\u003e\n  \u003c!-- (...) --\u003e\n\u003c/set\u003e\n```\n\nNaturally, the configuration with the import statement has always\nprecedence before the imported configuration. Please note that in\ncase of character maps, you can selectively overwrite single `char` mappings.\n\n### Inline XSLT\n\nYou can use XSLT everywhere in the configuration. This may be useful if\nyou need more programming features than the xml2tex configuration provides. So\nyou even can write your own XSLT functions include other XSLT stylesheets\nor make use of variables. \n\n```xml\n\u003cpreamble\u003e\n  \u003c!-- use german babel package when document language is 'de' --\u003e\n  \u003cxsl:if test=\"/*/@xml:lang eq 'de'\"\u003e\n    \u003cxsl:text\u003e\\usepackage[ngerman]{babel}\u003c/xsl:text\u003e\n  \u003c/xsl:if\u003e\n\u003cpreamble\u003e\n```\n\nThe configuration is converted to XSLT and then applied at the input. If something\nin your configuration is wrong, the stylesheet propably won't compile. In this case\nyou should set the `debug` option to `yes` and investigate the generated stylesheet in\n`{debug-dir-uri}/xm2tex/xml2tex01.config.xsl`.\n\n## MathML\n\nEquations specified in MathML syntax are automatically converted with the module [mml2tex](https://github.com/transpect/mml2tex).\n\n## Tables\n\nCALS tables are converted automatically converted to tabular tables. A XSLT stylesheet which converts also HTML tables is considered for a later release.\n\nThere are config options to allow a minimal set of customization:\n\n```xml\n\u003cset xmlns=\"http://transpect.io/xml2tex\"\n     table-model=\"tabular\"\n     table-grid=\"yes\"\n     table-col-declaration=\"c\"\n     table-first-col-declaration=\"l\"\n     table-last-col-declaration=\"r\"\u003e\n  \u003c!-- (...) --\u003e\n\u003c/set\u003e\n```\n\n* Permitted values for `table-model` are `tabular` and `tabularx`.\n* Choose `yes` or `no` for `table-grid` to select whether table grid lines should be rendered or not.\n* With `table-col-declaration` you can specify a custom column declaration for all table columns.\n* `table-first-col-declaration` affects the first table column and takes precedence over `table-col-declaration`.\n* `table-last-col-declaration` applies to the last table column and is preferred over `table-col-declaration`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranspect%2Fxml2tex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftranspect%2Fxml2tex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranspect%2Fxml2tex/lists"}