{"id":13961391,"url":"https://github.com/standardebooks/manual","last_synced_at":"2025-07-21T06:30:42.952Z","repository":{"id":39896727,"uuid":"251084979","full_name":"standardebooks/manual","owner":"standardebooks","description":"The source code for the Standard Ebooks Manual of Style.","archived":false,"fork":false,"pushed_at":"2024-11-25T19:24:55.000Z","size":515,"stargazers_count":136,"open_issues_count":4,"forks_count":35,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-25T20:26:51.253Z","etag":null,"topics":["ebooks","epub","publishing"],"latest_commit_sha":null,"homepage":"https://standardebooks.org/manual","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/standardebooks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2020-03-29T17:00:08.000Z","updated_at":"2024-11-25T19:24:51.000Z","dependencies_parsed_at":"2023-02-17T12:15:27.793Z","dependency_job_id":"da4849c5-f528-43c2-be38-ae5dc739ec48","html_url":"https://github.com/standardebooks/manual","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardebooks%2Fmanual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardebooks%2Fmanual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardebooks%2Fmanual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/standardebooks%2Fmanual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/standardebooks","download_url":"https://codeload.github.com/standardebooks/manual/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226878800,"owners_count":17696720,"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":["ebooks","epub","publishing"],"created_at":"2024-08-08T17:01:06.252Z","updated_at":"2025-07-21T06:30:42.939Z","avatar_url":"https://github.com/standardebooks.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Purpose and voice\n\nThe Standard Ebooks Manual of Style describes a complete approach to editing and producing ebooks, from internal code style to semantic enhancement and typography rules.\n\nIt is not a how-to manual; that is, it does not aim to give instructions on how to accomplish the various goals it describes. For example, it would not contain step by step guides, or guides on Inkscape usage, or SE toolset usage. Instead, the manual describes in declarative language how a Standard Ebook should appear after it is produced.\n\nEach directive is numbered and can contain any number of sub directives. Directives declare what the expected final appearance *is*, not how a producer *should achieve the final appearance*.\n\nFor example:\n\nGood: `“OK” is set without periods or spaces.`\n\nBad: `Don’t put periods or spaces in “OK”` or `“OK” shouldn’t be set with periods or spaces.`\n\n# Submitting changes\n\nThe `master` branch is reserved for typo fixes, clarifications, and version releases. Anything else should be committed to the `next` branch, which is periodically merged into `master` as a version release.\n\n# Installing\n\n## Ubuntu 24.04\n\n```shell\nsudo apt install python3-natsort pipx python3-bs4 python3-pygments\n\n# We require the Pip version of `rst2html5` as it's a new and improved version of the `docutils-common` apt package. See \u003chttps://pypi.org/project/rst2html5/\u003e.\npipx install rst2html5\n````\n\n## Ubuntu 20.04\n\n```shell\npip3 install beautifulsoup4 pygments natsort regex rst2html5\n```\n\n# Building\n\nTo build the final PHP files, invoke the `build-manual` executable:\n\n```shell\n./build-manual SOURCE_DIR DEST_DIR\n```\n\nTo generate the syntax highlighting stylesheet:\n\n```shell\npygmentize -S monokai -f html \u003e monokai.css\n```\n\n# Versioning\n\nThe overall version of the manual is stored as a comment in the `index.rst` file. This comment is used by `build-manual` to set the version number of the manual.\n\nWithin `.rst` files, the string `VERSION` is replaced with the version number when built. For example, a link to another part of the manual could be: `` `The SE identifier \u003c/manual/VERSION/9-metadata#9.2\u003e`__ ``.\n\n# Code style\n\n## Indentation\n\nAll indentation is with tabs, not spaces.\n\nA tab space follows the bullet point in all list items:\n\n```rst\n-\tList item 1\n\n-\tList item 2\n\n#.\tList item 1\n\n#.\tList item 2\n```\n\n## RST extensions\n\nSeveral additional RST roles are available for use in the manual:\n\n- HTML: `` :html:`\u003cp\u003eSome HTML\u003c/p\u003e` ``\n\n- CSS: `` :css:`.some-class{ font-weight: bold; }` ``\n\n- Bash: `` :bash:`se build --check .` ``\n\n- Paths: `` :path:`/standardebooks.org/web/www/` ``\n\n- Italics (`\u003ci\u003e`, not `\u003cem\u003e`): `` :italics:`The Iliad` ``\n\n- Whitespace: `` :ws:`hairsp` ``\n\n- UTF: `` :utf:`½` ``\n\n- HTML attribute value: `` :value:`A value of an HTML attribute` ``\n\n- String: `` :string:`A string that is not syntax highlighted` ``\n\nWhile they are not defined in each `.rst` file to avoid header clutter, they are defined by `build-manual` during the build process.\n\nYou may also create a tip or warning block:\n\n```rst\n.. tip::\n\n\tHere’s a tip!\n\n.. warning::\n\n\tHere’s a warning!\n```\n\nThe string `PD_YEAR` will be replaced with `\u003c?= PD_YEAR ?\u003e`, which will print the current public domain year when served from the SE website. For example, it will print `1926` if the current public domain includes works published up to and including 1926.\n\nThe string `PD_STRING` will be replaced with `\u003c?= PD_STRING ?\u003e`, which will print the first day the public domain ends when served from the SE website. For example, it will print `January 1, 1927` if the current public domain includes works published up to and including 1926.\n\n## Headings\n\n```rst\n####\n\u003ch1\u003e\n####\n\n\u003ch2\u003e\n****\n\n\u003ch3\u003e\n====\n\n\u003ch4\u003e\n----\n\n\u003ch5\u003e\n~~~~\n\n\u003ch6\u003e\n^^^^\n```\n\n## Numbered directives\n\nAll headings are automatically numbered and begin new `\u003csection\u003e` elements.\n\nNumbered directives begin with `#.\t` (Read: Hash, Period, Tab space) and begin new `\u003col\u003e` elements.\n\n```rst\n#.\tMajor structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a :html:`\u003csection\u003e` element.\n\n#.\tIndividual items in a larger collection (like a poem in a poetry collection) are contained in a :html:`\u003carticle\u003e` element.\n```\n\nSub-directives follow that convention, on the next indent level.\n\n```rst\n#.\t:html:`\u003cimg\u003e` elements have an :html:`alt` attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud.\n\n\t#.\tThe :html:`alt` attribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book.\n```\n\nTo create a heading that is not numbered, precede it with the `..no-numbering` class:\n\n```rst\n.. class:: no-numbering\n\nExamples\n--------\n\nConsider a book that contains several top-level subdivisions: Books 1–4, with each book having 3 parts, and each part having 10 chapters. Below is an example of three files demonstrating the structure necessary to achieve recomposability:\n```\n\n## Code samples\n\nBlock-level code samples are marked with the `.. code:: html` class:\n\n```rst\n.. code:: html\n\n\t\u003cimg alt=\"Pierre’s fruit-filled dinner\" src=\"...\" /\u003e\n```\n\nTo add the “green check” or “red x” styling, add the `.. corrected` or `.. wrong` class:\n\n```rst\n.. class:: wrong\n\n\t.. code:: html\n\n\t\t\u003cimg alt=\"The illustration for chapter 10\" src=\"...\" /\u003e\n\n.. class:: wrong\n\n\t.. code:: html\n\n\t\t\u003cimg alt=\"Pierre’s fruit-filled dinner\" src=\"...\" /\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstandardebooks%2Fmanual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstandardebooks%2Fmanual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstandardebooks%2Fmanual/lists"}