{"id":16374983,"url":"https://github.com/moderocky/autograph","last_synced_at":"2025-09-07T07:05:47.722Z","repository":{"id":235567533,"uuid":"790919504","full_name":"Moderocky/Autograph","owner":"Moderocky","description":"An extensible markup language with a simple design.","archived":false,"fork":false,"pushed_at":"2024-05-24T17:03:13.000Z","size":179,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-01T04:15:03.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Moderocky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-04-23T19:07:02.000Z","updated_at":"2024-05-24T17:03:16.000Z","dependencies_parsed_at":"2024-11-08T13:54:07.783Z","dependency_job_id":null,"html_url":"https://github.com/Moderocky/Autograph","commit_stats":null,"previous_names":["moderocky/autograph"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FAutograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FAutograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FAutograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moderocky%2FAutograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Moderocky","download_url":"https://codeload.github.com/Moderocky/Autograph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239954697,"owners_count":19724286,"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":[],"created_at":"2024-10-11T03:19:02.154Z","updated_at":"2025-02-21T04:25:45.065Z","avatar_url":"https://github.com/Moderocky.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Autograph\n=====\n\nAn extensible markup language with a simple design.\n\n# Introduction\n\n## Motivation\n\nLaTeX has been around since the 1980s: it is powerful, extensible, and has a package for every situation. \\\nIt is a nightmare that requires special training to use properly.\n\nHTML arrived in 1993: it is completely standardised, supported, and extensible. \\\nIt is also cumbersome, verbose, rigid, and inflexible.\n\nBBCode arrived in 1998: it is clear, commonplace and straightforward. \\\nIt is also clunky, limited and cheap.\n\n'Markdown' made its debut in 2004: it is fast, simple and easy to remember. \\\nUnfortunately, it lacks any standardisation, is filled with different parsing and rendering ambiguities from\nwebsite to website (Are underlines supported? Can you escape characters in code blocks? Is pure HTML allowed?)\nand although it professes to be extensible, this is in name only.\n\nMore to the point, none of these provide a universally-deployable system. XML does not make for a readable document,\nBBCode is too cumbersome to write and no longer seen outside old internet forums, and markdown does not offer\nthe kind of typesetting needed for anything above `README.md`s and blog posts.\nTeX and LaTeX are easily the most powerful, going into proper typesetting that only styled HTML can compete with.\nThe issue is, LaTeX is far too complex and advanced to set up and write anything time-sensitive with.\n\nMarkdown is not sufficient for articles or publication: it simply can't compare with the typesetting tools provided\nby other scripts. BBCode introduces more image tools, font colours, collapsible sections, but at the cost of being\ntricky and slow to write. LaTeX is big: big enough for publishing proofs, but far too big for anything less than that.\nThere is a reason universities have to run undergraduate workshops for learning to use LaTeX properly.\n\n### What does the perfect markup language look like?\n\nThis is a difficult question to answer: it must absorb all the benefits and advantages of existing markup languages\nwhile avoiding picking up any of their pitfalls and drawbacks.\n\n## Goals\n\n- Simple: easy to remember and to use, without interrupting the flow of the text while reading.\n- Flexible: extends to meet large, complex typesetting projects, squashes down to provide barebones comment styling.\n- Reliable: the same input must guarantee the same output.\n- Standardised: there must be some concept of inviolable rules, which all implementations must follow.\n\n# Design\n\n## Elements\n\nAutograph has two kinds of thing: text and commands.\n\nText is raw, written content, stored and displayed as-is (with the proper sanitation for its format).\n\nCommands are special instructions to the parser to format the inner content differently, or to insert some element.\n\nText and commands can (almost) always be mixed together, with the exception of special 'text-only' areas\nwhere special characters and formatting are not allowed (e.g. document window title \u0026 description).\n\n### Escape Character\n\nThe escape character is **backslash** ` \\ `. Placing a backslash before any character (e.g. `\u0026()\\`)\nwill prevent it from having a control effect.\nIn other words, if that character was supposed to do something special, it won't.\nThe backslash itself will not render.\n\nTo render a backslash, escape it with a second backslash: ` \\\\ `.\n\n### Text\n\nText is stored in text nodes.\n\nNodes are separated by two or more (consecutive) line breaks.\n\n```\nThis is text.\nThis is more text in the same node.\n\nThis is text in a different node.\n```\n\n### Commands\n\nCommands are stored in command nodes.\n\nCommands begin with an ampersand `\u0026`, followed by the command's name.\nThe command name is followed by the command header: opened by `(` and closed by `)`.\n\n```\n\u0026command label here(this is the command header)\n```\n\nAll commands need a header, even if they take no input.\n\n`\u0026emptyCommand()`\n\nThe processing of the command's header depends on the command used.\nSome commands may take one or more arguments, separated by a comma `,`.\n\n```\n\u0026my command(an argument, another argument)\n```\n\nCommands have complete authority over how to parse anything inside their `()` header.\n\nThe only rule is that they must terminate at a closing `)` bracket.\n\n# Standard Command Set\n\n## Text Formatting\n\nThese commands can contain text (and other commands).\n\n| Command        | Description                            | HTML Tag   |\n|----------------|----------------------------------------|------------|\n| `\u0026i(...)`      | Italic                                 | `\u003ci\u003e`      |\n| `\u0026b(...)`      | Bold                                   | `\u003cb\u003e`      |\n| `\u0026u(...)`      | Underline                              | `\u003cu\u003e`      |\n| `\u0026s(...)`      | Strikethrough                          | `\u003cs\u003e`      |\n| `\u0026q(...)`      | Quotation (inline)                     | `\u003cq\u003e`      |\n| `\u0026p(...)`      | Paragraph (explicit wrap)              | `\u003cp\u003e`      |\n| `\u0026em(...)`     | Emphasis (for screen reader)           | `\u003cem\u003e`     |\n| `\u0026strong(...)` | Strong (semantic importance)           | `\u003cstrong\u003e` |\n| `\u0026mark(...)`   | Highlight text                         | `\u003cmark\u003e`   |\n| `\u0026break()`     | Line break (new line in text)          | `\u003cbr\u003e`     |\n| `\u0026ruler()`     | Horizontal rule (line across document) | `\u003chr\u003e`     |\n| `\u0026code(...)`   | Code well: permits (balanced) brackets | `\u003ccode\u003e`   |\n\n## Block Elements\n\nThese commands are designed to take in multi-line content sections (and other commands).\n\n| Command        | Description                                  | HTML Tag         |\n|----------------|----------------------------------------------|------------------|\n| `\u0026aside()`     | An 'aside' block                             | `\u003caside\u003e`        |\n| `\u0026article()`   | An article section                           | `\u003carticle\u003e`      |\n| `\u0026quote()`     | A quote block                                | `\u003cblockquote\u003e`   |\n| `\u0026codeBlock()` | Code block well: permits (balanced) brackets | `\u003cpre\u003e` `\u003ccode\u003e` |\n| `\u0026details()`   | Collapsible details block.                   | `\u003cdetails\u003e`      |\n| `\u0026summary()`   | Details block summary.                       | `\u003csummary\u003e`      |\n\nNote: the `\u0026code` and `\u0026codeBlock` commands permit unescaped `(` parentheses `)`,\n**as long as** they are balanced.\n\n## Table Elements\n\n| Command    | Description            | HTML Tag  |\n|------------|------------------------|-----------|\n| `\u0026table()` | A table.               | `\u003ctable\u003e` |\n| `\u0026row()`   | A row in a table.      | `\u003ctr\u003e`    |\n| `\u0026cell()`  | A cell in a table row. | `\u003ctd\u003e`    |\n\n## Special Commands\n\nThese commands have special argument handling or parsing rules.\n\n### `\u0026comment`\n\nThe `\u0026comment(...)` command resolves to an empty node, not appearing in the final document.\nAny notes inside will not be visible in a compiled document.\n\n**Developer's note**: comments will produce an empty node in the document structure.\n\n### `\u0026link`\n\nWith a single argument, the `\u0026link(https://url)` command acts as an anchor `\u003ca\u003e` tag with an `href`.\nThe text inside the tag is the link itself.\n\nIf a second argument is provided, the `\u0026link(https://url, content here)` command acts as an anchor `\u003ca\u003e`\ntag with an `href`.\nThe content inside the tag is the second argument of the command.\n\n### `\u0026embed`\n\nThe `\u0026embed(Width by Height, source URL)` command is used to embed remote content (e.g. an image) in the document.\n\n```\n\u0026embed(500 by 450, https://my-website.com/my-image.png)\n```\n\nIts first argument is the embedded content size (in pixels), e.g. `600 by 300`.\nThis defines how much space the content is allowed to take up in the document page.\nSome content types may be stretched (or squashed) to fit, others may be clipped.\n\nThe second argument is a URL (link) to the content. The content type (e.g. image, text) will be inferred from\nthis link's file extension (`...test.png` -\u003e image, `...page.html` -\u003e html).\n\n### `\u0026ruby`\n\nThe `\u0026ruby(superscript, subscript)` command spreads (miniature) superscript text above regular content.\nThis is used for rendering language characters that have superscript modifications.\n\nTwo arguments are required: the text to go over the top, and the regular text to go beneath it.\n\nThe superscript text is block justified (stretched to fit the width of the element).\n\n**Note**: not all browsers support non-text elements in the superscript.\n\n### `\u0026html`\n\nThe `\u0026html(\u003cp\u003econtent\u003c/p\u003e)` command inserts unescaped HTML characters,\nallowing raw HTML to be written (providing the document is being compiled as HTML).\n\nIf this document is not being written as HTML the command will have no difference from regular text.\n\n### `\u0026softTable`\n\nThe 'soft table' command is for generating less rigid tables based on the content provided.\n\nThe first argument is the table dimensions, in the format `columns by rows`, e.g. `2 by 3`.\n\nEvery subsequent argument is inserted into the next available table cell. Unfilled cells are left empty.\nArguments exceeding the table's cell count are discarded.\n\n```\n\u0026softTable(2 by 3,\n  cell 1, cell 2,\n  cell 3, cell 4,\n  cell 5, cell 6\n)\n```\n\n## Article Commands\n\nAutograph is designed with journalistic article markup in mind.\nAs such, special support is given to commonly-used article elements (e.g. footnotes \u0026 citations).\n\n### `\u0026article`\n\nThis command wraps an entire 'article' node -- potentially the whole document.\nAnything inside an article is wrapped in an `\u003carticle\u003e` block during HTML compilation.\n\n```\n\u0026article(\n    Your content goes in here.\n    \n    This is arranged in paragraphs like a regular document.\n)\n```\n\nArticles are special; some content behaves differently or is only permitted inside them (e.g. footers, footnotes).\n\n### `\u0026header`\n\nA regular header block, designed to contain an article's header, abstract and other meta details.\n\n```\n\u0026header(\n    Your headnotes here!\n)\n```\n\n### `\u0026footer`\n\nA footer block, designed to be placed at the end of an article.\n\n```\n\u0026footer(\n    Your endnotes here!\n)\n```\n\nIf the footer is used in an article, and that article contains **footnotes**, these will be inserted\nat the bottom of their next footer.\n\n```\n\u0026footer(\n    Your endnotes here!\n    \n    \u0026comment(Footnotes would be inserted here!)\n)\n```\n\nIf an article contains multiple footer blocks, footnotes will be inserted only into the next one.\n\n### `\u0026footnote`\n\nThe `\u0026footnote(content here)` command is a powerful tool to inject references, notes and citations into a document.\n\nFootnotes can **only** be used within an article.\n\n```\n\u0026article(\n    ...as stated in my previous publication.\u0026footnote(\u0026i(The Odyssey), Homer, 800BC)\n    \n    \u0026footer(References:)\n)\n```\n\nThe footnote command produces an anchor link (e.g. `1`) in its location.\nThe actual content of the footnote is then added to the next `\u0026footer` notes list.\n\n#### Rendering Example\n\n\u003carticle class=\"ag-article\"\u003e\n    \u003cp\u003e...as stated in my previous publication.\u003csup class=\"ag-reference\"\u003e\u003ca href=\"#footnote-ebb08fe6\"\u003e1\u003c/a\u003e\u003c/sup\u003e\u003c/p\u003e\n    \u003cfooter class=\"ag-footer\"\u003e\n        \u003cp\u003eReferences:\u003c/p\u003e\n        \u003cdl class=\"ag-footnote\" id=\"footnote-ebb08fe6\"\u003e\n            \u003cdt\u003e1\u003c/dt\u003e\n            \u003cdd\u003e\n                \u003cp\u003e\u003ci\u003eThe Odyssey\u003c/i\u003e, Homer, 800BC\u003c/p\u003e\n            \u003c/dd\u003e\n        \u003c/dl\u003e\n    \u003c/footer\u003e\n\u003c/article\u003e\n\n---\n\nFootnote numbering will restart whenever a footer consumes the available references.\n\nArticles containing footnotes **must** contain a footer to display them in.\n\n### `\u0026cite`\n\nThe citation command is designed for inserting sourced quotes.\n\nIts first argument is a reference/url (like `\u0026link`) followed by its content.\nThe citation switches between inline and block-mode based on its content.\n\nCitations (of either inline or block type) have the `.ag-citation` class applied in HTML compilation.\n\nWhen compiled to HTML, in-text citations inject a little source `span` note at the end.\n\n#### Inline (in-text)\n\n```\nThe empire state building is \u0026cite(https://bad-facts, 5 metres tall)!\n```\n\n#### Block (in-text)\n\n```\n\u0026cite(https://my-rubbish-poem, \n    O empire state\n    You are pretty tall\n    I myself am not \n    Quite 5 metres\n)\n```\n\n#### Footnote Citations\n\nA footnote can be the target of a citation, either in inline or block mode.\nThis will add the footnote anchor to the citation rather than citing a URL.\n\nAs with regular footnotes, this can only be used within an `\u0026article` that has a `\u0026footer` to display the footnote.\n\n```\n\u0026cite(\u0026footnote(\u0026i(Epic Poem), B. Shakespeare, 2006), \n    O empire state\n    You are pretty tall\n    I myself am not \n    Quite 5 metres\n)\n```\n\nThe above example will insert the numbered anchor, and then add the citation (_Epic Poem_, B. Shakespeare, 2006)\nto the footnotes of the article.\n\nMultiple footnotes may be used in a citation. This will add multiple anchors after the quote.\n\n```\n\u0026cite(\u0026footnote(foo)\u0026footnote(bar), \n    O empire state\n    You are pretty tall\n    I myself am not \n    Quite 5 metres\n)\n```\n\n**Note**: if something _other than_ a footnote is used in a footnote citation, this will inject an in-text citation as\nwell.\n\n### `\u0026figure`\n\nThe `\u0026figure(ID, content)` command inserts a referencable figure block into the document.\nThis can contain images, tables, etc. and will be separated from the rest of the content.\n\nFigures can be referenced by their ID, so it is important that every figure is given a unique ID.\nThis ID is used to substitute the numeric index of the figure when the document is assembled,\nto create standard references (e.g. Figure 1, Fig. 1).\n\n```\n\u0026article(\n    \u0026figure(My fantastic poem,\n        Did you want to try\n        Escaping a bracket here\n        To make a nice face? :\\)\n    ) \n)\n```\n\nThe figure ID will not be visible anywhere in the rendered document, so it can be anything convenient.\n\n```\n\u0026figure(SomeTableOfData, ...) \n```\n\n### `\u0026caption`\n\nThe `\u0026caption(text)` command can be used within figures to add a named caption.\nThis will contain an automatic reference to the figure's index in the article (e.g. Figure 1).\n\n```\n\u0026article(\n    \u0026figure(SurveyDataByAge,\n        Content goes here...\n        \n        \u0026caption(The survey results arranged by age group.)\n    ) \n)\n```\n\n### `\u0026fig`\n\nThe figure reference `\u0026fig(ID)` command is used to insert an indexed reference to a figure in the same article.\n\nIts only parameter is the ID used in the `\u0026figure(ID, ...)` command.\n\n```\n\u0026article(\n    \u0026figure(SurveyDataByAge, blah blah)\n    \n    As seen in \u0026fig(SurveyDataByAge), ...\n)\n```\n\nForward and backward references are both permitted.\n\n```\n\u0026article(\n    If you refer to \u0026fig(SurveyDataByAge), you will see that...\n\n    \u0026figure(SurveyDataByAge, blah blah)\n)\n```\n\n**Note**: if a figure reference is made to a figure that is _never_ written, it will take up an index at the\nend of the figure set.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoderocky%2Fautograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoderocky%2Fautograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoderocky%2Fautograph/lists"}