= OurBigBook Project {c} {id=ourbigbook} = OurBigBook Project {c} {synonym} The OurBigBook Project aims to create the ultimate tool to publish textbooks/<#personal knowledge bases>/<#Zettelkasten>/<#digital gardens> in the <#learn in public> philosophy, and to be our best shot yet at the final real-world <#Encyclopedia Galactica> by allowing effective <#mindmeld>[mind melding]/<#collective intelligence>. \Image[logo.svg] {height=150} {title=[Logo of] the OurBigBook Project} Mission: to live in a world where you can learn university-level <#mathematics>, <#physics>, <#chemistry>, #biology and #engineering from perfect free open source books that anyone can write to get famous. Ultimate goal: destroy the currently grossly inefficient education system and replace it with a much more inspiring system where people learn what they want as fast as possible to reach their goals faster without so much useless pain. How to get there: [create a website] that incentivizes learners (notably university students taking courses) to write freely licensed university-level natural science books in their own words for free. Their motivation for doing that are: * getting their knowledge globally recognized and thus better jobs * improving the world * learning by teaching Notable features: * focus on <#mindmeld>[mind melding]/<#collective intelligence> via the [topics feature], which makes your articles easier for others to find with a sort-by upvote <#Stack Overflow>-like view of multiple users articles on the same topic \Video[https://www.youtube.com/watch?v=54nxjC9BWTg] {title= demo} {disambiguate=intro} {height=700} {width=700} * you can store all your data locally in a [plaintext markup format] that can be edited locally and published in various ways, including as a \Video[https://www.youtube.com/watch?v=Ghvlztiu6rI] {title=Edit locally and publish demo} {disambiguate=intro} {description=This shows editing and it using the extension.} {height=720} {width=720} The website is the main tool of the project. is another complementary tool. * https://OurBigBook.com[]: reference instance * donate to the OurBigBook Project: * https://twitter.com/OurBigBook[]: announcements. Other official accounts at: {full} * https://cirosantilli.com/ourbigbook-com[]: further rationale behind the project * https://cirosantilli.com[]: showcase static demo document with interesting content, published with . Primary inspiration for OurBigBook development. * https://cirosantilli.com/oxford-nanopore-river-bacteria[]: a self-contained tutorial style part of the above. Note how internal links integrate seamlessly into the more global topic of biology, e.g. when talking about DNA we link to the global topic https://cirosantilli.com/dna[]. * https://github.com/cirosantilli/cirosantilli.github.io[] and https://github.com/cirosantilli/cirosantilli.github.io/blob/dev/oxford-nanopore-river-bacteria.bigb[]: source of the above showcase documents * {full}: and feature overview * https://github.com/ourbigbook/ourbigbook[]: OurBigBook source code * https://github.com/ourbigbook/ourbigbook/issues[]: project issue tracker * https://github.com/ourbigbook/ourbigbook/blob/master/README.bigb[]: source for this document * https://docs.ourbigbook.com[]: rendered version of this document * https://docs.ourbigbook.com/editor[]: live in-browser editor demo * https://github.com/ourbigbook/template[]: good template to get started with , see {full} * https://ourbigbook.github.io/template[]: the above * https://cirosantilli.com/ourbigbook-media[]: media for the project such as for documentation and , more info: {full} = Donate {parent=OurBigBook} You can donate to the to sponsor its development in the following ways: * https://cirosantilli.com/sponsor[]: give money directly to Ciro Santilli, who is currently the sole maintainer and developer of the project. If things ever grow in scope we will set up a foundation and register a charity for it. One may dream. * by project merchandise, see: {full} We are happy to discuss paid contracts to implement specific features, to get in touch see: . = Quick start {parent=OurBigBook} The following sections cover different ways to use tools from the OurBigBook: * : manual for , the dynamic website. This is what most users will use by default when it is matured;. * : allows you to convert local `.bigb` files from the command line to either: * a static website. This is already very usable. * upload to . Almost very usable, we're getting there. * : covers specifically , which is the markup language you use to write content in OurBigBook, both and . This is currently the only way to write OurBigBook content, but we would really like to add [WYSIWYG] editor support one day! = OurBigBook Markup and CLI overview {parent=OurBigBook} = Features {parent=OurBigBook Markup and CLI overview} * to any
(including e.g. h2, h3, etc. [in other files]), , etc. with amazing [error checking and reporting]: never break internal links without knoing again, and quickly find out what broke when you do. E.g.: animal.bigb `` = Animal are . `` Mammal.bigb `` = Flying animal == Bat `` `Animal.bigb` would render something like: `` Bats are flying animals. `` The following would fail and point you out the file and line of the failure: * nonexistent id: `` `` * duplicate IDs: `` = Animal == Dog == Cat == Dog `` * https://katex.org/[KaTeX] server side , works on browsers with JavaScript disabled: `` I like $\sqrt{2}$, but I adore this \x[equation-quadratic-equation]: $$ x^2 + 2x + 1 $$ {title=Quadratic equation} `` * multi-file features out of the box so you don't need a separate wrapper like Jekyll to make a multi-page website: * * single-source multi-format output based on and build options: * by default, one HTML per source with includes rendered as links between pages, e.g.: README.bigb `` = My website == h2 \Include[not-readme] `` not-readme.bigb `` = Not readme == Not readme h2 `` produces `index.html` and `not-readme.html` * with the option, you can output each header of an input file into a separate output file. The previous filesystem would produce: * `index.html`: which contains the full `README.bigb` output * `split.html`: split version of the above containing only the `= My website` header and not `h2` * `h2.html`: only contains the `h2` header * `not-readme.html` contains the full output of `not-readme.bigb` * `not-readme-split.html`: only contains the `= Not readme` header * `not-readme-h2.html`: only contains the `= Not readme h2` header Each of those pages automatically gets a * <--embed-includes> single file output from multiple input files. Includes are parsed smartly, not just source copy pasted, e.g. included headers are shifted from `h1` to `h2` correctly. On the previous sample filesystem, it would produce a single output file `index.html` which would contain a header structure like: `` = My website == h2 === Not readme ==== Not readme h2 `` * supports both local serverless rendering to HTML files for local viewing, and server oriented rendering such as GitHub pages, e.g. automatically get `.html` extension and or not. E.g.: * locally, a link `\x[not-readme]` would render as `` and `not-readme.bigb` produces `not-readme.html` * when publishing, `\x[not-readme]` would render as `` and `not-readme.bigb` also produces `not-readme.html`, which the server converts to just `http://my-website.com/not-readme` * cross file configuration files to factor out common page parts like headers, footers and other metadata, e.g.: * `ourbigbook.liquid.html`: https://github.com/Shopify/liquid[Liquid template] used for all pages, see example at: {full} * `main.scss`: CSS stylesheet generated from https://sass-lang.com/[SASS] input, see example at: {full} * `ourbigbook.tex`: global LaTeX math definitions, e.g.: `` \newcommand{\abs}[1]{\left|#1\right|} `` and then you can use: `` $\abs{x}$ `` in any .bigb file of the project. * : per repository configuration options *
that crosses input files via includes. E.g. in: README.bigb `` = My website == h2 \Include[not-readme] `` not-readme.bigb `` = Not readme == Not readme h2 `` the table of contents for `index.html` also contains the headers for `not-readme.bigb` producing: * My website * h2 * Not readme * Not readme h2 This means that you can split large <\H splitDefault argument>[splitDefault] input files if rendering starts to slow you down, and things will still render exactly the same. * check that local files and images linked to actually exist: <\a external argument>. E.g.: `` \a[i-don-exist.txt] `` would lead to a build error. * associate headers to files or directories with the <\H file argument> e.g.: `` Here's an example of a nice image: \x[path/to/my/image.png]{file}. = path/to/my/image.png {file} This image was taken when I was on vacation! `` would automatically add a preview of the image on the output. Display files and their metadata nicely directly on your static website rather than relying exclusively on GitHub as a file browser. * advanced header/ID related features: * : `` = Furry animal I like \x[furry-animal]{p}, especially my cat, here is his photo: \x[image-my-cat]. == Cat \Image[My_cat.jpg] {title=My cat} `` * either with directories or with within a single file: `` See the important conclusion of my experiment: \x[report-of-my-experiment/conclusion] = Report of my experiment {scope} == Introduction == Middle == Conclusion `` * for capitalization and pluralization, e.g.; `` = Dog == Snoopy {c} \x[dog]{c}{p} are fun. But the \x[dog] I like the most is \x[snoopy]! `` would render: * `\x[dog]{c}{p}` as `Dogs`: capitalized because of `{c}` and pluralized because of `{p}` * `\x[dog]` as `dogs`: auto lowercased because its header `= Dog` does not have `{c}` * `\x[snoopy]` as `Snoopy`: title capitalization kept to upper case due to `{c}` on the header `== Snoopy` * , e.g.: `` = User interface = UI {c} {synonym} {title2} \x[user-interface]{c} is too long, I just say \x[ui]. `` would render something like: `` User interface is too long, I just say UI `` Furthermore, this also generates a output file: `` ui.html `` which redirects to the ain `user-interface.html`, so it serves as a way to have backward compatibility on page renames. And the `title2` makes it appears on the main title under parenthesis, something like: ``

User interface (UI)

`` * <\H disambiguate argument>[header disambiguation], e.g.: `` My favorite fruits are \x[apple-fruit]{p}! My favorite least favorite brand is is \x[apple-company]! \x[apple] computers are too expensive. == Apple {disambiguate=fruit} == Apple {c} {disambiguate=company} = Apple {c} {synonym} `` which renders something like: * `\x[apple-fruit]{p}`: `apples` * `\x[apple-company]`: `Apple` * `\x[apple]`: also `Apple` because of the synonym * `== Apple\n{disambiguate=fruit}`: `

Apple (fruit)

` * `== Apple\n{disambiguate=company}`: `

Apple (company)

` * tags are regular headers: <\H child argument>, <\x child argument> `` = Animal == Dog {tag=domestic} {tag=cute} == Cat {tag=domestic} {tag=cute} == Bat {tag=flying} = Flying = Cute = Domestic `` * , levels higher than 6 are rendered in HTML as an appropriately styled `div`s with an ID: `` = h1 == h2 === h3 ==== h4 ===== h5 ====== h6 ======= h7 ======== h8 `` * generate lists of between internal headers: it shows every internal link coming into the current page * automatic file upload and directory listing of non OurBigBook files: <`_raw` directory>, e.g.: * link to a file: \OurBigBookExample[[ The file \a[index.js] is cool. ]] * link to a directory: \OurBigBookExample[[ The directory \a[file_demo] is cooler. ]] * is written in JavaScript and therefore runs natively on the browser to allow live previews as shown at: https://docs.ourbigbook.com/editor[] * helps you with the publishing: * publishes in a single command to the configured target (default ) * OurBigBook tries to deal with media such as images and video intelligently for you, e.g.: {full}. E.g. you can keep media in a separate media repository, `my-media-repository`, and then by configuring on : `` "media-providers": { "github": { "default-for": ["image", "video"], "path": "media", "remote": "yourname/myproject-media" } } `` you can use images in that repository with: `` \Image[My_image_basename.jpg] `` instead of: `` \Image[https://raw.githubusercontent.com/cirosantilli/myproject--media/master/My_image_basename.jpg] `` * `inotifywait` watch and automatically rebuild with : `` ourbigbook --watch input-file.bigb `` * automatic code formatting: <--format-source> = Design goals {parent=OurBigBook Markup and CLI overview} OurBigBook is designed entirely to allow writing complex professional HTML and PDF scientific books, blogs, articles and encyclopedias. OurBigBook aims to be the ultimate [LaTeX] "killer", allowing books to be finally published as either HTML or PDF painlessly (LaTeX being only a backend to PDF generation). It aims to be [more powerful] and and than Markdown and Asciidoctor. = Saner {parent=Design goals} Originally, OurBigBook was is meant to be both saner and more powerful than Markdown and Asciidoctor. But alas, as Ciro started implementing and using it, he started to bring some Markdown [insanity he missed back in]. And so this "degraded" slightly into a language slightly saner than Asciidoctor but with an amazing Node.js implementation that makes it better for book writing and website publishing. Notably, we hope that our escaping will be a bit saner backslash escapes everything instead of Asciidoctor's "different escapes for every case" approach: https://github.com/asciidoctor/asciidoctor/issues/901 But hopefully, having starting from a saner point will still produce a saner end result, e.g. there are sane constructs for every insane one. It is intended that this will be an acceptable downside as OurBigBook will be used primarily large complex content such as books rather than forum posts, and will therefore primarily written either: * in text editors locally, where users have more features than in random browser textareas * in a dedicated website that will revolutionize education, and therefore have a good JavaScript editing interface: https://github.com/cirosantilli/write-free-science-books-to-get-famous-website For example, originally OurBigBook had exactly five magic characters, with similar functions as in LaTeX: * `\` backslash to start a macro, like LaTeX * `{` and `}`: left and right square brackets to delimit [optional macro arguments] * `[` and `]`: left and right curly braces bracket to start an optional arguments and double blank newlines for if you are pedantic, but this later degenerated into many more with . We would like to have only square brackets for both optional and mandatory to have even less magic characters, but that would make the language difficult to parse for computer and humans. LaTeX was right for once! This produces a very regular syntax that is easy to learn, including doing: * arbitrary nesting of elements * adding arbitrary properties to elements This sanity also makes the end tail learning curve of the endless edge cases found in Markdown and Asciidoctor disappear. The language is designed to be philosophically isomorphic to HTML to: * further reduce the learning curve * ensure that most of HTML constructs can be reached, including arbitrary nesting More precisely: * macro names map to tag names, e.g.: `\\a` to `Link text<>`. = More powerful {parent=Design goals} The [high sanity of OurBigBook], also makes creating new macro extensions extremely easy and intuitive. All built-in language features use the exact same API as new extensions, which ensures that the extension API is sane forever. Markdown is clearly missing many key features such as block attributes and , and has no standardized extension mechanism. The "more powerful than Asciidoctor" part is only partially true, since Asciidoctor is very featureful can do basically anything through extensions. The difference is mostly that OurBigBook is completely and entirely focused on making amazing scientific books, and so will have key features for that application out-of-the box, notably: * amazing header/ToC/ID features including proper error reports: never have a internal broken link or duplicate ID again * [server side pre-rendered maths with KaTeX]: all divs and spans are ready, browser only applies CSS, no JavaScript gets executed * : we take care of website publishing for you out-of-the-box, no need to integrate into an external project like Jekyll * : * https://github.com/asciidoctor/asciidoctor/issues/626 feature request * https://github.com/owenh000/asciidoctor-multipage third party plugin that does it and we feel that some of those features have required specialized code that could not be easily implemented as a standalone macro. Another advantage over Asciidoctor is that the reference implementation of OurBigBook is in JavaScript, and can therefore be used on browser live preview out of the box. Asciidoctor does Transpile to JS with https://github.com/opal/opal[Opal], but who wants to deal with that layer of complexity? = Related projects {parent=Design goals} Static wiki generators: this is perhaps the best way of classifying this project :-) * https://github.com/gollum/gollum[]: already has a local server editor! But no WYSIWYG nor live preview. Git integration by default, so when you save on the UI already generates a Git commit. We could achieve that with: https://github.com/isomorphic-git/isomorphic-git[], would be really nice. Does not appear to have built-in static generation: * https://stackoverflow.com/questions/7210391/have-anyone-use-gollum-site-to-generete-markdown-wikis-and-host-it-on-heroku * https://github.com/dreverri/gollum-site Does not appear to check that any links are correct. * https://github.com/wcchin/markypydia * https://obsidian.md/ closed source, Markdown with + a SaaS. Appears to require payment for any publishing. 28k followers 2021: https://twitter.com/obsdmd[]. Founders are likely Canadians of Asian descent from Waterloo University: https://www.linkedin.com/in/lishid/ | https://www.linkedin.com/in/ericaxu/ also working in parallel on https://dynalist.io/ 2020 review at: https://www.youtube.com/watch?v=aK2fOQRNSxc Has offline editor with side-by-side preview. Compares with https://roamresearch.com/[Roam] and https://roamresearch.com/[Notion], but can't find any public publishing on those, seem to be enterprise only things. Static book generators: * https://github.com/rstudio/bookdown[], https://bookdown.org/[]. Very similar feature set to what we want!!! Transpiles to markdown, and then goes through Pandoc: https://bookdown.org/yihui/bookdown/pandoc.html[], thus will never run on browser without huge translation layers. But does have an obscene amount of output formats however. * https://gohugo.io/[Hugo]. Pretty good, similar feature set to ours. But Go based, so hard on browser, and adds adhoc features on top of markdown once again * https://en.wikipedia.org/wiki/Personal_wiki * https://github.com/vimwiki/vimwiki * https://github.com/hplgit/doconce * https://www.gwern.net/About#source is pretty interesting, uses https://github.com/jaspervdj/Hakyll/ + some custom stuff. * https://github.com/JerrySievert/bookmarkdown * https://www.gitbook.com/ * https://github.com/rust-lang/mdBook[]. Impressive integrated search feature. Like Gitbook but implemented in Rust. * https://github.com/facebook/docusaurus React + markdown based, written in TypeScript. So how can it be build fast? Gotta benchmark. * vimdoc: http://vimdoc.sourceforge.net/ They do have perfectly working , see any page e.g. http://vimdoc.sourceforge.net/htmldoc/pattern.html[]. * typst: https://github.com/typst/typst An attempt at a LaTeX killer. Has its own typesetting engine, does not simply transpile to LaTeX. Meant to be faster and simpler to write. No HTML output as of writing: https://github.com/typst/typst/issues/721 Less related but of interest, similar philosophy to what Ciro wants, but no explicitly reusable system: * http://www.uprtcl.io/ * https://libretexts.org * https://physics.info/ * https://hypertextbook.com/ * https://tutorial.math.lamar.edu/ = Motivation {parent=Design goals} Ciro Santilli developed OurBigBook to perfectly satisfy his writing style, which is basically "create one humongous document where you document everything you know about a subject so everyone can understand it, and just keep adding to it". https://cirosantilli.com[] is the first major document that he has created in OurBigBook. He decided to finally create this new system after having repeatedly facing limitations of Asciidoctor which were ignored/wontfixed upstream, because Ciro's writing style is not as common/targeted by Asciidoctor. Following large documents Ciro worked extensively on: * https://github.com/cirosantilli/china-dictatorship * https://github.com/cirosantilli/linux-kernel-module-cheat made the limitations of Asciidoctor clear to Ciro, and were major motivation in this work. The key limitations have repeatedly annoyed Ciro were: * cannot go over header level 6, addressed at: * the need for to avoid one too large HTML output that will never get indexed properly by search engines, and takes a few seconds to load on any browser, which is unacceptable user experience = OurBigBook Markup {c} {parent=OurBigBook} = `.bigb` extension {synonym} {title2} OurBigBook Markup is the https://en.wikipedia.org/wiki/Lightweight_markup_language[lightweight markup language] used in the project. It works both on the dynamic website, and on static websites from the command line. files use the `.bigb` extension. = OurBigBook Markup quick start {c} {parent=OurBigBook Markup} are made by simplying adding an empty line, e.g.: \OurBigBookExample[[ My first paragraph. And now my second paragraph. Third one to finish. ]] are created by starting the line with equal signs. The more equal signs the deeper you are, e.g.: `` = Animal == Mammal === Dog === Cat == Bird === Pigeon === Chicken `` On , the toplevel header of each page goes into a separate title box, so there things would just look like: * title box: "Animal" * body: `` == Mammal === Dog === Cat == Bird === Pigeon === Chicken `` You can can use any header as a <`\H` `tag` argument>[tag] of any other header, e.g.: `` = Animal == Dog {tag=Cute animal} == Turtle {tag=Ugly animal} == Animal cuteness === Cute animal === Ugly animal `` Headers have several powerful features that you can read more about under <`\H` arguments>, e.g. <`\H` `synonym` argument> and <`\H` `disambiguate` argument>. To [link to any of your other pages], you can use angle brackets (less than/greater than) signs: `` I have a . are too noisy. `` Note how [capitalization and pluralization generally just work]. To use a custom link text on a reference, use the following syntax: `` I have a [furry animal]. [feathery animals] are too noisy. `` External links can be input directly as: \OurBigBookExample[[ This is a great website: https://example.com I really like https://example.com[this website]. ]] are done with backticks \c[[`]]. With just one backtick, you get a code block inside the text: \OurBigBookExample[[ The function call `f(x + 1, "abc")` is wrong. ]] and with two ore more backticks you get a code block on its own line, and possibly with multiple code lines: \OurBigBookExample[[ The function: `` function f(x, s) { return x + s } `` is wrong. ]] syntax is very similar to code blocks, you can just enter you LaTeX code in it: \OurBigBookExample[[ The number $\sqrt{2}$ is irrational. The same goes for: $$ \frac{1}{\sqrt{2}} $$ ]] We also have [a bunch of predefined macros from popular packages], e.g. `\dv` from the https://mirrors.ibiblio.org/CTAN/macros/latex/contrib/physics/physics.pdf[`physics` package] for derivatives: \OurBigBookExample[[ $$ \dv{x^2}{x} = 2x $$ ]] You can [refer] to specific equations like this: \OurBigBookExample[[ As shown in , this is true. $$ \frac{1}{\sqrt{2}} $$ {title=Very important equation} ]] and are also easy to add and [refer] to: \OurBigBookExample[[ As shown at , chicks are cute. \Image[https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/H%C3%BChnerk%C3%BCken_02.jpg/800px-H%C3%BChnerk%C3%BCken_02.jpg?20200716091201] {title=Cute chicken chick} \Video[https://www.youtube.com/watch?v=j_fl4xoGTKU] {title=Top Down 2D Continuous Game by Ciro Santilli (2018)} ]] Images can take a bunch of options, about which you can read more about at . Most should be self explanatory, here is an image with a bunch of useful arguments: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/H%C3%BChnerk%C3%BCken_02.jpg/800px-H%C3%BChnerk%C3%BCken_02.jpg?20200716091201] {title=Ultra cute chicken chick} {description= The chicken is yellow, and the hand is brown. The background is green. } {border} {height=400} {source=https://commons.wikimedia.org/wiki/File:H%C3%BChnerk%C3%BCken_02.jpg} ]] are written by starting the line with an asterisk `*`: \OurBigBookExample[[ * first item * second item * and the third ]] A nested list: \OurBigBookExample[[ * first item * first item version 1 * first item version 2 * first item version 2 1 * first item version 2 2 * second item * and the third ]] Lists items can contain any markup, e.g. paragraphs. You just need to keep the same number of spaces, e.g.: \OurBigBookExample[[ * first item. Second paragraph of first item. And a third one. * second item * second item v1 Another paragraph in second item v1 * second item v2 ]] are not very different from lists. We use double pipes for headers `||`, and a single pipe `|` for regular rows: \OurBigBookExample[[ || City || Sales | Salt Lake City | 124,00 | New York | 1,000,000 ]] To add a title we need to use an explicit `\Table` macro as in: \OurBigBookExample[[ See
for more information. \Table {title=Sales per city} [ || City || Sales | Salt Lake City | 124,00 | New York | 1,000,000 ] ]] = Macro {parent=OurBigBook Markup} This section documents all OurBigBook macros. Macros are magic commands that do cool stuff, e.g. `\Image` to create an image. The most common macros also have to keep the syntax shorter. The general macro syntax is described at {full}. = Link {parent=Macro} = `\a` {synonym} {title2} = `\a` macro {synonym} autolink, i.e. the link text is the same as the link address: \OurBigBookExample[[ The website http://example.com is cool. See also: \Q[http://example.com/2] ]] Exact parsing rules described at: {full}. Note that the prefixes `http://` and `https://` are automatically removed from the displayed link, since they are so common that they woudly simply add noise. Equivalent sane version: \OurBigBookExample[[[ The website \a[http://example.com] is cool. \Q[\a[http://example.com/2]] ]]] Insane link with custom text: \OurBigBookExample[[The website http://example.com[example.com] is cool.]] Equivalent sane version: \OurBigBookExample[[The website \a[http://example.com][example.com] is cool.]] If the custom text is empty, an autolink is generated. This is often useful if you want your link to be followed by punctuation: \OurBigBookExample[[The website is really cool: http://example.com[].]] This could also be achieved with the sane syntax of course, but this pattern saves a tiny bit of typing. Link with multiple paragraphs inside it: \OurBigBookExample[[ \a[http://example.com][Multiple paragraphs] ]] Link to a file in the current repository: \OurBigBookExample[[ The file \a[index.js] is cool. ]] This links to a raw view of that file. Link to a directory in the current repository: \OurBigBookExample[[ The directory \a[file_demo] is cooler. ]] This links to an output file that contains a generated directory listing of that directory. = `\a` `href` argument {parent=Link} The link target, e.g. in: `` \a[http://example.com] `` `href` equals `http://example.com`. Important behaviours associated with this property for local links are detailed at <\a external argument>{full}: * they are checked for existence in the local filesystem * they are modified to account for with = `\a` `ref` argument {parent=Link} Analogous to the <\x ref argument>, e.g.: \OurBigBookExample[[Trump said this and that.https://en.wikipedia.org/wiki/Donald_Trump_Access_Hollywood_tape#Trump's_responses{ref}https://web.archive.org/web/20161007210105/https://www.donaldjtrump.com/press-releases/statement-from-donald-j.-trump{ref} Then he said that and this.https://en.wikipedia.org/wiki/Donald_Trump_Access_Hollywood_tape#Trump's_responses{ref}https://web.archive.org/web/20161007210105/https://www.donaldjtrump.com/press-releases/statement-from-donald-j.-trump{ref}]] = `\a` `external` argument {parent=Link} {tag=Boolean argument} If given and true, forces a the link to be an . Otherwise, the external is automatically guessed based on the address given as explained at {full}. Common use cases for the `external` argument is to link to non OurBigBook content in the curent domain, e.g.: * for * link non OurBigBook subdirectories. E.g., https://github.com/cirosantilli/cirosantilli.github.io/blob/master/README.bigb was rendered at https://cirosantilli.com[], and contains links `\a[markdown-style-guide]{external}` to https://cirosantilli.com/markdown-style-guide[], whose source lives in a separate non-OurBigBook repository: https://github.com/cirosantilli/markdown-style-guide/ = Internal links are smart {parent=`\a` `external` argument} = Link to the domain root path {synonym} {title2} The <`\a` `external` argument> can be used to refer to the root of the domain. E.g. suppose that we have a under `https://mydomain.com/subdir/`. Then: * `\a[/somepath]` refers to the directory `/subdir/somepath` * `\a[/somepath]{external}` refers t othe directory `/somepath` = Subdirectory deployment {parent=a `external` argument} TODO test if it works. But we want it to be possible to deploy static websites on subdirectories, e.g.: `` https://mydomain.com/subdir/ https://mydomain.com/subdir/mathematics `` If it doesn't work, it should be easy to make it work, as we use relative links almost everywhere already. Likely there would only be some minor fixes to the <--template> arguments. = External link {parent=a `external` argument} = Internal link {synonym} An external link is a link that points to a resource that is not present in the curent OurBigBook project sources. By default, most links are internal links, e.g. it is often the case in computer programming tutorials that we want to refer to source files in the current directory. So from our `README.bigb`, we could want to write something like: \OurBigBookExample[[Have a look at this amazing source file: \a[index.js].]] and here `\a[ourbigbook]` is a internal link. A typicial external link is something like: \OurBigBookExample[[This is great website: https://cirosantilli.com]] which points to an absolute URL. OurBigBook considers a link relative by default if: * it is not a Therefore, the following links are external by default: * `http://cirosantilli.com` * `https://cirosantilli.com` * `file:///etc/fstab` * `ftp://cirosantilli.com` and the following are internal by default: * `index.js` * `../index.js` * `path/to/index.js` * `/path/to/index.js`. Note that paths starting with `/` refer to the root of the deployment, not the root of the domain, see: . * `//example.com/path/to/index.js` A link being internal has the following effects * the correct relative path to the file is used when using nested with . For example, if we have: `` = h1 == h2 {scope} === h3 \a[index.js] `` then in split header mode, `h3` will be rendered to `h2/h3.html`. Therefore, if we didn't do anything about it, the link to `index.js` would render as `href="index.js"` and thus point to `h2/index.js` instead of the correct `index.js`. Instead, OurBigBook automatically converts it to the correct `href="../index.js"` * the <`_raw` directory> prefix is added to the link * existence of the file is checked on compilation. If it does not exist, an error is given. Implemented at: https://github.com/ourbigbook/ourbigbook/issues/87[] as `relative`, and subsequently modified to the more accurate/useful `external`. = `_dir` directory {parent=a `external` argument} The `_dir` directory tree contains file listings of files in the `_raw` directory. We originally wanted to place these listings under `_raw` itself, but this leads to unsolvable conflicts when there are files called `index.html` present vs the index. = `_file` output directory {parent=a `external` argument} = `_file` directory {synonym} Analogous to the <`_raw` directory>, but for the <`\H` `file` argument>. = `_raw` directory {parent=a `external` argument} places output files that are not the output of `.bigb` to `.html` conversion (i.e. `.html` output files) under the `_raw/` prefix of the output. then automatically add the `_raw/` prefix to every link. For example, consider an input directory that contains: notindex.bigb `` = Hello Check out \a[myfile.c]. The source code for this file is at: \a[notindex.bigb]. \Image[myimg.png] `` myfile.c `` int i = 1; `` myimg.png `` Binary! `` After conversion with: `` ourbigbook . `` the following files would exist in the output directory: * `notindex.html`: converted output of `notindex.bigb` * `_raw/notindex.bigb`: a copy of the input source code `notindex.bigb` * `_raw/myfile.c`: a copy of the input file `myfile.c` * `_raw/myimg.png`: a copy of the input file `myimg.c` and all links/image references would work and automtically point to the correct locations under `_raw`. Some live examples: * link to a file: \OurBigBookExample[[ The file \a[index.js] is cool. ]] * link to a directory: \OurBigBookExample[[ The directory \a[file_demo] is cooler. ]] The reason why a `_raw` prefix is needed it to avoid naming conflicts with OurBigBook outputs, e.g. suppose we had the files: * `configure` * `configure.bigb` Then, in a server that omits the `.html` extension, if we didn't have `_raw/` both `configure.html` and `configure` would be present under `/configure`. With `_raw` we instead get: * `_raw/configure`: the input `/configure` file * `configure`: the HTML = URL with protocol {c} {parent=a `external` argument} A URL with protocol is a URL that matches the regular expression `^[a-zA-Z]+://`. The following are examples of URLs with protocol: * `http://cirosantilli.com` * `https://cirosantilli.com` * `file:///etc/fstab` * `ftp://cirosantilli.com` The following aren't: * `index.js` * `../index.js` * `path/to/index.js` * `/path/to/index.js` * `//example.com/path/to/index.js`. This one is a bit tricky. Web browsers would consider this as a https://stackoverflow.com/questions/28446314/why-use-protocol-relative-urls-at-all[protocol-relative URL], which technically implies a protocol, although that protocol would be different depending how you are viewing the file, e.g. locally through `file://` vs on a with website `https://`. For simplicity's sake, we just consider it as a URL without protocol. = Insane link parsing rules {parent=Link} Insane start at any of the recognized protocols are the ones shown at: {full}. * `http://` * `https://` absolutely anywhere if not escaped, e.g.: `` ahttp://example.com `` renders something like: `` a `` To prevent expansion, you have to escape the protocol with a backslash `\\`, e.g.: `` \http://example.com `` Empty domains like: `` http:// `` don't becomes links however. But this one does: `` http://a `` Insane links end when any is found. As a consequence, to have an insane link followed immediately by a punctuation like a period you should use an empty argument as in: \OurBigBookExample[[Check out this website: http://example.com[].]] otherwise the punctuation will go in it. Another common use case is: \OurBigBookExample[[As mentioned on the tutorial (http://example.com[see this link]).]] If you want your link to include one of the terminating characters, e.g. `]`, all characters can be escaped with a backslash, e.g.: \OurBigBookExample[[Hello http://example.com/\]a\}b\\c\ d world.]] Note that the `http://example.com` inside `\a[http://example.com]` only works because we do some post-processing magic that prevents its expansion, otherwise the link would expand twice: \OurBigBookExample[[ \P[http://example.com] \a[http://example.com] ]] This magic can be observed with <--help-macros> by seeing that the `href` argument of the `a` macro has the property: `` "elide_link_only": true, `` = Insane link termination character {parent=Insane link parsing rules} The following characters are the "insane link termination characters": * space ` ` * newline `\n` * open or close square bracket `[` or `]` * open or close curly braces `{` or `}` and terminate if any of these characters are found, see also: {full}. = Bold {parent=Macro} {title2=`\b`} \OurBigBookExample[[Some \b[bold] text.]] = Line break {parent=Macro} {title2=`\br`} There is basically one application for this: poetry, which would be too ugly with due to fixed width font: \OurBigBookExample[[ Paragraph 1 Line 1\br Paragraph 1 Line 2\br Paragraph 2 Line 1\br Paragraph 2 Line 2\br ]] = Code block {parent=Macro} {title2=\c[[``]], \c[[`]], `\C`, `\c`} Inline code (code that should appear in the middle of a paragraph rather than on its own line) is done with a single backtick (\c[[`]]) : \OurBigBookExample[[My inline `x = 'hello\n'` is awesome.]] and block code (code that should appear on their own line) is done with two or more backticks (\c[[``]]): \OurBigBookExample[[ `` f() { return 'hello\n'; } `` ]] The sane version of inline code is a lower case `c`: \OurBigBookExample[[[My inline \c[[x = 'hello\n']] is awesome.]]] and the sane version of block math is with an upper case `C`: \OurBigBookExample[[[ \C[[ f() { return 'hello\n'; } ]] ]]] The capital vs lower case theme is also used in other elements, see: . If the content of the sane code block has many characters that you would need to [escape], you will often want to use , which work just like the do for any other argument. For example: \OurBigBookExample[[[[ \C[[[ A paragraph. \C[[ And now, some long, long code, with lots of chars that you would need to escape: \ [ ] { } ]] A paragraph. ]]] ]]]] Note that the initial newline is skipped automatically in code blocks, just as for any other element, due to: , so you don't have to worry about it. The distinction between inline `\c` and block `\C` code blocks is needed because in HTML, https://stackoverflow.com/questions/5371787/can-i-have-a-pre-tag-inside-a-p-tag-in-tumblr/58603596#58603596[`pre` cannot go inside `P`]. We could have chosen to do some magic to differentiate between them, e.g. checking if the block is the only element in a paragraph, but we decided not to do that to keep the language saner. And now a code block outside of <\OurBigBookExample> to test how it looks directly under : `` Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello HelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHello Hello `` Now with short description with math and underline: `` Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello HelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHello Hello `` {description=My long code! $a_b$} And now a very long inline code: `Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello` \Comment[[[[ TODO implement. We can have cross references to code blocks as for other elements such as \x[image]{p}: \OurBigBookExample[[[ See this awesome code \x[my-code]: `` ab cd `` {id=my-code} ]]] ]]]] = `\C` argument {parent=Code block} = `\C` `description` argument {parent=`\C` argument} {tag=`description` argument} See: <`description` argument>{full}. Example: \OurBigBookExample[[ See the: . `` print("Hello wrold") `` {title=Python hello world} {description=Note thow this is super short unlike the C hello world!} ]] = `\C` `title` argument {parent=`\C` argument} {tag=`title` argument} See: <`title` argument>{full}. Example: \OurBigBookExample[[ See the: . `` #include int main(void) { puts("hello, world"); } `` {title=C hello world} ]] = Comment {parent=Macro} {title2=`\Comment`} The `Comment` and `comment` macros are regular macros that does not produce any output. Capitalization is explained at: {full}. You will therefore mostly want to use it with a [literal argument], which will, as for any other macro, ignore any macros inside of it. \OurBigBookExample[[[ Before comment. \Comment[[ Inside comment. ]] After comment. ]]] And an inline one: \OurBigBookExample[[[ My inline \comment[[inside comment]] is awesome. \comment[[inside comment]] inline at the start. ]]] = Header {parent=Macro} {title2=`\H`} with `= ` (equal sign space): `` = My h1 == My h2 === My h3 `` Insane headers end at the first newline found. They cannot therefore contain raw newline tokens. Equivalent sane: `` \H[1][My h1] \H[2][My h2] \H[3][My h3] `` Custom ID for on insane headers: `` = My h1 {id=h1} == My h2 {id=h2} === My h3 {id=h3} `` Sane equivalent: `` \H[1][My h1]{id=h1} \H[2][My h2]{id=h2} \H[3][My h3]{id=h3} `` = Unlimited header levels {parent=Header} There is no limit to how many levels we can have, for either sane or insane headers! HTML is randomly limited to `h6`, so OurBigBook just renders higher levels as an `h6` with a `data-level` attribute to indicate the actual level for possible CSS styling: ``
My title
`` The recommended style is to use insane headers up to `h6`, and then move to sane one for higher levels though, otherwise it becomes very hard to count the `=` signs. To avoid this, we considered making the insane syntax be instead: `` = 1 My h1 = 2 My h2 = 3 My h3 `` but it just didn't feel as good, and is a bit harder to type than just smashing `=` n times for lower levels, which is the most common use case. So we just copied markdown. = My h3 {parent=Unlimited header levels} = My h4 {parent=My h3} = My h5 {parent=My h4} = My h6 {parent=My h5} = My h7 {parent=My h6} = My h8 {parent=My h7} = My h9 {parent=My h8} = My h10 {parent=My h9} = My h11 {parent=My h10} = My h12 {parent=My h11} = My h13 {parent=My h12} = Skipping header levels {parent=Header} The very first header of a document can be of any level, although we highly recommend your document to start with a `\H[1]`, and to contain exactly just one `\H[1]`, as this has implications such as: * `\H[1]` is used for the document title: * `\H[1]` does not show on the
After the initial header however, you must not skip a header level, e.g. the following would give an error because it skips level 3: `` = my 1 == my 1 ==== my 4 `` = The toplevel header {parent=Header} = Toplevel header {synonym} The toplevel header of a OurBigBook file is its first header and the one with the lowest level, e.g. in a document with recommended syntax: `` = Animal == Dog === Bull Terrier == Cat `` the header `= Animal` is the tolevel header. Being the toplevel header gives a header some special handling described in child sections of the section and elsewhere throughout this documentation. The toplevel header is only defined if the document has only a single header of the highest level. e.g. like the following has only a single `h2`: `` == My 2 === My 3 1 === My 3 2 `` = The toplevel header IDs don't show {parent=The toplevel header} Header IDs won't show for the toplevel level. For example, the headers would render like: `` My 2 1. My 3 1 2. My 3 2 `` rather than: `` 1. My 2 1.2. My 3 1 1.2. My 3 2 `` This is because in this case, we guess that the `h2` is the toplevel. = The ID of the first header is derived from the filename {parent=The toplevel header} TODO: we kind of wanted this to be the ID of the toplevel header instead of the first header, but this would require an extra postprocessing pass (to determine if the first header is toplevel or not), which might affect performance, so we are not doing it right now. When the OurBigBook input comes from a file (and not e.g. ), the default ID of the first header in the document is derived from the basename of the OurBigBook input source file rather than from its title. This is specially relevant when [including] other files. For example, in file named `my-file.bigb` which contains: `` = Awesome ourbigbook file ]] `` the ID of the header is `my-file` rather than `awesome-ourbigbook-file`. See also: . If the file is an other than , then the basename of the parent directory is used instead, e.g. the toplevel ID of a file: `` my-subdir/README.bigb `` would be: `` #my-subdir `` rather than: `` #README.bigb `` For the toplevel index file however, the ID is just taken from the header itself as usual. This is done because you often can't general control the directory name of a project. For example, a [GitHub pages] root directory must be named as `.github.io`. And users may need to rename directories to avoid naming conflicts. As a consequence of this, the toplevel index file cannot [be included in other files]. = `\H` arguments {parent=Header} = `\H` `c` argument {parent=H arguments} If given, makes the header capitalized by default on . More details at: {full}. = `\H` `child` argument {parent=H arguments} This marks given IDs as being children of the current page. The effect is the same as adding the <\x child argument> argument to an under the header. Notably, such marked target IDs will show up on the autogenerated
. Example: `` = Animal == Mammal === Bat === Cat == Wasp == Flying animal {child=bat} {child=wasp} \x[bat] \x[wasp] `` renders exactly as: `` = Animal == Mammal === Bat === Cat == Wasp == Flying animal \x[bat]{child} \x[wasp]{child} `` The header `child` syntax is generally preferred because at some point while editing the content of the header, you might accidentally remove mentions to e.g. `\x[bat]{child}`, and then the relationship would be lost. The <\H tag argument> does the same as the <\x child argument> but in the opposite direction. = `\H` `file` argument {parent=H arguments} If given, the current section contains metadata about file or other resource with the given URL. If empty, the URL of the file is extracted directly from the header. Otherwise, the given URL is used. for example: `` = path/to/myfile.c {file} An explanation of what this file is about. `` renders a bit like: ``` = path/to/myfile.c {id=_file/path/to/myfile.c} An explanation of what this file is about. \a[path/to/myfile.c] `` // Contents of path/to/myfile.c int main() { return 1; } `` ``` so note how: * does not normalize the path, e.g. it does not convert `/` to `-`. Also, a <_file output directory>[`_file/` prefix] is automatically added to the ID. This is needed with to avoid a collision between: * `path/to/myfile.c`: the actual file * `_file/path/to/myfile.c`: the metadata about that file. Note that locally the `.html` extension is added as in `file/path/to/myfile.c.html` which avoids the collision. But on a server deployment, the `.html` is not present, and there would be a conflict if we didn't add that `file/` prefix. * a link to the is added automatically, since users won't be able to click it from the header, as clicking on the header will just link to the header itself * a preview is added. The type of preview is chosen as follows: * if the URL has an image extension, do an preview * otherwise if the URL has a video extension, or is a YouTube URL, do a
links * with the <\x full argument> This option can be set by default for all files with: By default, headers are numbered as in a book, e.g.: `` = h1 == h2 === h3 ==== h4 `` renders something like: `` = h1 Table of contents * 1. h2 * 1.1. h3 * 1.1.1. h4 == 1. h2 === 1.1. h3 ==== 1.1.1. h4 `` However, for documents with a very large number of sections, or [deeply nested headers] those numbers start to be more noise than anything else, especially in the table of contents and you are better off just referring to IDs. E.g. imagine: `` 1.3.1.4.5.1345.3.2.1. Some deep level `` When documents reach this type of scope, you can disable numbering with the `numbered` option. This option can be set on any header, and it is inherited by all descendants. The option only affects descendants. E.g., if in the above example turn numbering off at `h2`: `` = h1 == h2 {numbered=0} === h3 ==== h4 `` then it renders something like: `` = h1 Table of contents * 1. h2 * h3 * h4 == 1. h2 === h3 ==== h4 `` The more common usage pattern to disable it on toplevel and enable it only for specific "tutorial-like sections". An example can be seen at: * https://cirosantilli.com/[]: huge toplevel wiki, for which we don't want numbers * https://cirosantilli.com/x86-paging[]: a specific tutorial, for which we want numbers which is something like: `` = Huge toplevel wiki {numbered=0} == h2 === A specific tutorial {numbered} {scope} ==== h4 ===== h5 `` then it renders something like: `` = Huge toplevel wiki Table of contents * h2 * A specific tutorial * 1. h4 * 1.1. h5 == h2 === A specific tutorial ==== 1. h4 ===== 1.1. h5 `` Note how in this case the number for `h4` is just `1.` rather than `1.1.1.`. We only show numberings relative to the first non-numbered header, because the `1.1.` wouldn't be very meaningful otherwise. = `\H` `parent` argument {c} {parent=H arguments} = ID-based header levels {c} {synonym} {title2} In addition to the basic way of specifying header levels with an explicit level number as mentioned at
{full}, OurBigBook also supports a more indirect ID-based mechanism with the `parent` argument of the `\H` element. We hightly recommend using `parent` for all but the most trivial documents. For example, the following fixed level syntax: `` = My h1 == My h2 1 == My h2 2 === My h3 2 1 `` is equivalent to the following ID-based version: `` = My h1 = My h2 1 {parent=my-h1} = My h2 2 {parent=my-h1} = My h3 2 1 {parent=my-h2-h} `` The main advantages of this syntax are felt when you have a huge document with [very large header depths]. In that case: * it becomes easy to get levels wrong with so many large level numbers to deal with. It is much harder to get an ID wrong. * when you want to move headers around to improve organization, things are quite painful without a refactoring tool (which we intend to provide in the ), as you need to fix up the levels of every single header. If you are using the ID-based syntax however, you only have to move the chunk of headers, and change the `parent` argument of a single top-level header being moved. Note that when the `parent=` argument is given, the header level must be `1`, otherwise OurBigBook assumes that something is weird and gives an error. E.g. the following gives an error: `` = My h1 == My h2 {parent=my-h1} `` because the second header has level `2` instead of the required `= My h2`. When are involved, the rules are the same as those of internal reference resolution, including the leading `/` to break out of the scope in case of conflicts. Like the <\H child argument>, `parent` also performs on the argument, allowing you to use the original spaces and capitalization in the target as in: `` = Flying animal = Bat {parent=Flying animal} `` which is equivalent to: `` = Flying animal = Bat {parent=flying-animal} `` See also:
{full} for further rationale. = ID-based header levels and scope resolution {c} {parent=H parent argument} When mixing both <\H parent argument> and , things get a bit complicated, because when writing or parsing, we have to first determine the parent header before resolving scopes. As a result, the follow simple rules are used: * start from the last header of the highest level * check if the `{parent=XXX}` is a suffix of its ID * if not, proceed to the next smaller level, and so on, until a suffix is found Following those rules for example, a file `tmp.bigb`: `` = h1 {scope} = h1 1 {parent=h1} {scope} = h1 1 1 {parent=h1-1} = h1 1 2 {parent=h1-1} = h1 1 3 {parent=h1/h1-1} = h1 2 {parent=h1} {scope} = h1 2 1 {parent=h1-2} {scope} = h1 2 1 1 {parent=h1-2/h1-2-1} `` will lead to the following header tree with <--log headers>: `` = h1 tmp == h2 1 tmp/h1-1 === h3 1.1 tmp/h1-1/h1-1-1 === h3 1.2 tmp/h1-1/h1-1-2 === h3 1.3 tmp/h1-1/h1-1-3 == h2 2 tmp/h1-2 === h3 2.1 tmp/h1-2/h1-2-1 ==== h4 2.1.1 tmp/h1-2/h1-2-1/h1-2-1-1 `` = Header explicit levels vs nesting design choice {parent=H parent argument} Arguably, the language would be even saner if we did: `` \H[My h1][ Paragraph. \H[My h2][] ] `` rather than having explicit levels as in `\H[1][My h1]` and so on. But we chose not to do it like most markups available because it leads to too many nesting levels, and hard to determine where you are without tooling. Ciro later "invented" (?) <\H parent argument>, which he feels reaches the perfect balance between the advantages of those two options. = `\H` `scope` argument {parent=H arguments} = Scope {synonym} In some use cases, the sections under a section describe inseparable parts of something. For example, when documenting an experiment you executed, you will generally want an "Introduction", then a "Materials" section, and then a "Results" section for every experiment. On their own, those sections don't make much sense: they are always referred to in the context of the given experiment. The problem is then how to get unique IDs for those sections. One solution, would be to manually add the experiment ID as prefix to every subsection, as in: `` = Experiments See: \x[full-and-unique-experiment-name/materials] == Introduction == Full and unique experiment name === Introduction {id=full-and-unique-experiment-name/introduction} See our awesome results: \x[full-and-unique-experiment-name/results] For a more general introduction to all experiments, see: \x[introduction]. === Materials {id=full-and-unique-experiment-name/materials} === Results {id=full-and-unique-experiment-name/results} `` but this would be very tedious. To keep those IDs shorter, OurBigBook provides the `scope` property of , which works analogously to C++ namespaces with the header IDs. Using `scope`, the previous example could be written more succinctly as: `` = Experiments See: \x[full-and-unique-experiment-name/materials] == Introduction == Full and unique experiment name {scope} === Introduction See our awesome results: \x[results] For a more general introduction to all experiments, see: \x[/introduction]. === Materials === Results `` Note how: * full IDs are automatically prefixed by the parent scopes prefixed and joined with a slash `/` * we can refer to other IDs withing the current scope without duplicating the scope. E.g. `\x[results]` in the example already refers to the ID `full-and-unique-experiment-name/materials` * to refer to an ID outside of the scope and avoid name conflicts with IDs inside of the current scope, we start a reference with a slash `/` So in the example above, `\x[/introduction]` refers to the ID `introduction`, and not `full-and-unique-experiment-name/introduction`. = `scope` resolution {parent=H scope argument} When nested scopes are involved, resolution peels off the scopes one by one trying to find the closes match, e.g. the following works as expected: `` = h1 {scope} == h2 {scope} === h3 {scope} \x[h2] `` Here OurBigBook: * first tries to loop for an `h1/h2/h3/h2`, since `h1/h2/h3` is the current scope, but that ID does not exist * so it removes the `h3` from the current scope, and looks for `h1/h2/h2`, which is still not found * then it removes the `h2`, leading to `h1/h2`, and that one is found, and therefore is taken = Directory-based `scope` {parent=H scope argument} Putting files in subdirectories of the build has the same effect as adding a to their top level header. Notably, all headers inside that directory get the directory prepended to their IDs. The toplevel directory is determined as described at: . = Test scope 1 {parent=H scope argument} {scope} For fun and profit. = Test scope 2 {parent=Test scope 1} {scope} Let's break this local link: \a[ourbigbook]. = Not scoped {parent=Test scope 2} = `\H` `scope` argument of toplevel headers {parent=H scope argument} When is given the `scope` property OurBigBook automatically uses the file path for the scope and heaves fragments untouched. For example, suppose that file `full-and-unique-experiment-name` contains: `` = Full and unique experiment name {scope} == Introduction == Materials `` In this case, multi-file output will generate a file called `full-and-unique-experiment-name.html`, and the URL of the subsections will be just: * `full-and-unique-experiment-name.html#introduction` * `full-and-unique-experiment-name.html#materials` instead of * `full-and-unique-experiment-name.html#full-and-unique-experiment-name/introduction` * `full-and-unique-experiment-name.html#full-and-unique-experiment-name/materials` Some quick interactive cross file link tests: * * * = `\H` `splitDefault` argument {parent=H arguments} When using , always point to non-split pages as mentioned at . If the `splitDefault` is given however: * the split header becomes the default, e.g. `index.html` is now the split one, and `nosplit.html` is the non-split one * the header it is given for, and all of its descendant headers will use the split header as the default internal cross target, unless the header is already rendered in the current page. This does not propagate across however. For example, consider `README.bigb`: `` = Toplevel {splitDefault} \x[h2][toplevel to h2] \x[notreadme][toplevel to notreadme] \Include[notreadme] == h2 `` and `notreadme.bigb`: `` = Notreadme \x[h2][notreadme to h2] \x[notreadme][notreadme to notreadme h2] == Notreadme h2 `` Then the following links would be generated: * `index.html`: split version of `README.bigb`, i.e. does not contain `h2` * `toplevel to h2`: `h2.html`. Links to the split version of `h2`, since `h2` is also affected by the `splitDefault` of its parent, and therefore links to it use the split version by default * `toplevel to notreadme`: `notreadme.html`. Links to non-split version of `notreadme.html` since that header is not `splitDefault`, because `splitDefault` does not propagate across includes * `nosplit.html` non-split version of `README.bigb`, i.e. contains `h2` * `toplevel to h2`: `#h2`, because even though `h2` is `splitDefault`, that header is already present in the current page, so it would be pointless to reload the split one * `toplevel to notreadme`: `notreadme.html` * `h2.html` split version of `h2` from `README.bigb` * `notreadme.html`: non-split version of `notreadme.bigb` * `notreadme to h2`: `h2.html`, because `h2` is `splitDefault` * `notreadme to notreadme h2`: `#notreadme-h2` * `notreadme-split.html`: split version of `notreadme.bigb` * `notreadme to h2`: `h2.html`, because `h2` is `splitDefault` * `notreadme to notreadme h2`: `notreadme.html#notreadme-h2`, because `notreadme-h2` is not `splitDefault` The major application of this if you like work with a huge `README.bigb` containing thousands of random small topics. Splitting those into separate source files would be quite laborious, as it would require duplicating IDs on the filename, and setting up . However, after this README reaches a certain size, page loads start becoming annoyingly slow, even despite already loading large assets like video only on hover or click: the annoying slowness comes from the loading of the HTML itself before the browser can jump to the ID. And even worse: this README corresponds to the main index page of the website, which will make what a large number of users will see be that slowness. Therefore, once this README reaches a certain size, you can add the `splitDefault` attribute to it, to make things smoother for readers. And if you have a smaller, more self-contained, and highly valuable tutorial such as https://cirosantilli.com/x86-paging[], you can just split that into a separate `.bigb` source file. This way, any links into the smaller tutorial will show the entire page as generally desired. And any links from the tutorial, back to the main massive README will link back to split versions, leading to fast loads. This feature was implemented at: https://github.com/ourbigbook/ourbigbook/issues/131 Note that this huge README style is not recommended however. Ciro Santilli used to do it, but moved away from it. The currently recommended approach is to manually create not too large subtrees in each page. This way, readers can easily view several nearby sections without having to load a new page every time. = `\H` `splitSuffix` argument {parent=H arguments} If given, add a custom suffix to the output filename of the header when using . If the given suffix is empty, it defaults to `-split`. For example, given: `` = my h1 == my h2 `` a `--split-headers` conversion would normally place `my h2` into a file called: `` my-h2.html `` However, if we instead wrote: `` == my h2 {splitSuffix} `` it would not be placed under: `` my-h2-split.html `` and if we set a custom one as: `` == my h2 {splitSuffix=asdf} `` it would go instead to: `` my-h2-asdf.html `` This option is useful if the root of your website is written in OurBigBook, and you want to both: * have a section that talks about some other project * host the documentation of that project inside the project source tree For example, https://cirosantilli.com with source at https://github.com/cirosantilli/cirosantilli.github.io has a quick section about OurBigBook: https://cirosantilli.com#ourbigbook[]. Therefore, without a custom suffix, the split header version of that header would go to https://docs.ourbigbook.com[], which would collide with this documentation, that is present in a separate repository: https://github.com/ourbigbook/ourbigbook[]. Therefore a `splitSuffix` property is used, making the split header version fall under `/ourbigbook-split`, and leaving the nicer `/ourbigbook` for the more important project toplevel. If given on the , which normally gets a suffix by default to differentiate from the non-split version, it replaces the default `-split` suffix with a custom one. For example if you had `notindex.bigb` as: `` = Not index `` then it would render to: `` notindex-split.bigb `` but if you used instead: `` = Not index {splitSuffix=asdf} `` then it would instead be: `` notindex-asdf.bigb `` = `\H` `synonym` argument {parent=H arguments} = Synonym {synonym} This option is similar to <\H title2 argument> but it additionally: * creates a new ID that you can refer to, and renders it with the alternate chosen title * the rendered ID on is the same as what it is a synonym for * the synonym header is not rendered at all, including in the
* when using , a redirect output file is generated from the synonym to the main ID Example: `` = Parent == GNU Debugger {c} = GDB {c} {synonym} I like to say \x[gdb] because it is shorter than \x[gnu-debugger]. `` renders something like: `` = GNU Debugger I like to say \a[#gnu-debugger][GDB] because it is shorter than \x[#gnu-debugger][GNU Debugger]. `` Furthermore, if is used, another file is generated: `` gdb.html `` which contains a redirection from `gdb.html` to `gnu-debugger.html`. Implemented at: https://github.com/ourbigbook/ourbigbook/issues/114 = `\H` `title` argument {parent=H synonym argument} {tag=`title` argument} Contains the main content of the header. The : `` = My title `` is equivalent to the sane: `` \H[1][My title] `` and in both cases `My title` is the title argument. The <`title` argument> is also notably used for . = Automatic ID from title {parent=H title argument} If a [non-toplevel] macro has the `title` argument is present but no explicit `id` argument is given, an is created automatically from the `title`, by applying the following transformations: * do a conversion on the title to remove for example any HTML tags that would be present in the conversion output * convert all characters to lowercase. This uses . Note that this does convert non-ASCII characters to lowercase, e.g. `É` to `é`. * if is `true` (the default) do . This converts e.g. `é` to `e`. * if is `true` (the default) do . This converts e.g. `+` to `plus`. * convert consecutive sequences of all non `a-z0-9` ASCII characters to a single hyphen `-`. Note that this leaves non-ASCII characters untouched. * strip leading or trailing hyphens Note how those rules leave non-ASCII Unicode characters untouched, except for: * capitalization changes wher applicable, e.g. `É` to `é` as capitalization and determining if something "is a letter or not" in those cases can be tricky. For toplevel headers, see: . So for example, the following automatic IDs would be generated:
. \Table[ || title || id || latin normalization || punctuation normalization || comments | My favorite title | my-favorite-title | | | | Ciro's markdown is awesome | ciro-s-markdown-is-awesome | | | `'` is an ASCII character, but it is not in `a-z0-9`, therefore it gets converted to a hyphen `-` | É你 | e你 | true | | The Latin https://en.wikipedia.org/wiki/Acute_accent[acute accented] `e`, `É`, is converted to its lower case form `é` as per the . Then, due to , `é` is converted to `e`. The Chinese character `你` is left untouched as Chinese characters have no case, and no ASCII analogue. | É你 | é你 | false | | Same as the previous, but `é` is not converted to `e` since is turned off. | C++ is great | c-plus-plus-is-great | | true | This is the effect of . | I \i[love] dogs. | i-love-dogs | | | `love` is extracted from the italic tags `love` with conversion. | β Centauri | beta-centauri | | | Our Latin normalization is amazing and knows Greek! ] {title=Examples of automatically generated IDs} For [the toplevel header], its ID is derived from the basename of the OurBigBook file without extension instead of from the `title` argument. TODO: * maybe we should also remove some or all non-ASCII punctuation. All can be done with `\\p{IsPunctuation}`: https://stackoverflow.com/questions/13925454/check-if-string-is-a-punctuation-character but we need to check that we really want to remove all of them. = ID target from title {c} {parent=H synonym argument} This conversion type is similar to , but it is used in certain cases where we are targeting IDs rather than setting them, notably: * <\H parent argument> * <\H child argument> * <\H tag argument> = `\H` `title2` argument of a synonym header {parent=H synonym argument} Unlike <\H title2 argument>, the synonym does not show up by default next to the title. This is because we sometimes want that, and sometimes not. To make the title appear, you can simply add an empty `title2` argument to the synonym header as in: `` = GNU Debugger {c} = GDB {c} {synonym} {title2} = Quantum computing = Quantum computer {synonym} `` which renders something like: `` = GNU Debugger (GDB) = Quantum computing `` Note how we added the synonym to the title only when it is not just a simple flexion variant, since `Quantum computing (Quantum computer)` would be kind of useless would be kind of useless. = `\H` `tag` argument {c} {parent=H arguments} {tag=multiple argument} = Tag {synonym} Same as <\x child argument> but in the opposite direction, e.g.: `` == Mammal === Bat {tag=flying-animal} === Cat == Flying animal `` is equivalent in every way to: `` == Mammal === Bat === Cat == Flying animal {child=bat} `` Naming rationale: * `parent` as the opposite of child is already taken to be then "main parent" via the "<\H parent argument>" * we could have renamed the <\H child argument> to `tags` as in "this header tags that one", but it would be a bit confusing `tags` vs `tag` So `child` vs `tag` it is for now. You generally want to use `tag` instead of the <\H child argument> because otherwise some very large header categories are going to contain Huge lists of children, which is not very nice when editing. It is possible to enforce the <\H child argument> or the <\H tag argument> in a given project with the option. = `\H` `title2` argument {parent=H arguments} {tag=multiple argument} The `title2` argument can be given to any element that has the `title` argument. Its usage is a bit like the `description=` argument of , allowing you to add some extra content to the header without affecting its ID. Unlike `description=` however, `title2` shows up on all <\x full argument>[`full`] references, including appearances in the
, which make it more searchable. Its primary use cases are: * give acronyms, or other short names names of fuller titles such as mathematical/programming notation One primary reason to not use the acronyms as the main section name is to avoid possible ID ambiguities with other acronyms. * give the header in different languages For example, given the OurBigBook input: `` = Toplevel The Toc follows: == North Atlantic Treaty Organization {c} {title2=NATO} \x[north-atlantic-treaty-organization] \x[north-atlantic-treaty-organization]{full} `` the rendered output looks like: `` = Toplevel The ToC follows: * North Atlantic Treaty Organization (NATO) == North Atlantic Treaty Organization (NATO) North Atlantic Treaty Organization Section 1. "North Atlantic Treaty Organization (NATO)" `` Related alternatives to `title2` include: * <\H disambiguate argument> when you do want to affect the ID to remove ambiguities * <\H synonym argument> Parenthesis are added automatically around all rendered `title2`. The `title2` argument has a special meaning when applied to a
with the <\H synonym argument>, see <\H title2 argument of a synonym header>. \Comment[[ = `\H` `tutorial` argument {parent=h-arguments} {tag=boolean-argument} This option is a convenience helper for the common use case of "writting a tutorial". The same would also apply to a report, or an article. ]] = `\H` `toplevel` argument {parent=H arguments} {tag=Boolean argument} When the `\H` `toplevel` argument is set, the header and its descendants will be automatically output to a separate file, even without <--split-headers>. For example given: animal.bigb `` = Animal == Vertebrate === Dog {toplevel} ==== Bulldog == Invertebrate `` and if you convert as: `` ourbigbook animal.bigb `` we get the following output files: * `animal.html`: contains the headers: "Animal", "Vertebrate" and "Invertebrate", but not "Dog" and "Bulldog" * `dog.html`: contains only the headers: "Dog" and "Bulldog" This option is intended to produce output identical to using and separate files, i.e. the above is equivalent to: animal.bigb `` = Animal == Vertebrate \Include[dog] == Invertebrate `` dog.bigb `` = Dog {toplevel} == Bulldog `` Or in other words: of each source file gets `{toplevel}` set implicitly for it by default. This design choice might change some day. Arguably, the most awesome setup is on in which source files and outputs are completely decoupled. also essentially wants this, as ideally we want to store one source per header there in each DB entry. We shall see. = `\H` `wiki` argument {parent=H arguments} If given, show a link to the Wikipedia article that corresponds to the header. If a value is not given, automatically link to the Wiki page that matches the header exactly with spaces converted to underscores. Here is an example with an explicit wiki argument: `` ==== Tiananmen Square {wiki=Tiananmen_Square} `` which looks like: = Tiananmen Square {id=wiki-explicit} {parent=H wiki argument} {wiki=Tiananmen_Square} or equivalently with the value deduced from the title: `` = Tiananmen Square {wiki} `` which looks like: = Tiananmen Square {id=wiki-implicit} {parent=H wiki argument} {wiki} You can only link to subsections of wiki pages with explicit links as in: `` = History of Tiananmen Square {{wiki=Tiananmen_Square#History}} `` which looks like: = History of Tiananmen Square {id=wiki-explicit-subsection} {parent=H wiki argument} {{wiki=Tiananmen_Square#History}} Note that in this case, you either need a `{{}}` or to explicitly escape the `#` character as in: `` = History of Tiananmen Square {wiki=Tiananmen_Square\#History} `` to avoid the creation of an . Also note that Wikipedia subsections are not completely stable, so generally you would rather want to link to a permalink with a full URL as in: `` = Artificial general intelligence {wiki=https://en.wikipedia.org/w/index.php?title=Artificial_general_intelligence&oldid=1192191193#Tests_for_human-level_AGI} `` Note that in this case escaping the `#` is not necessary because it is part of the that starts at `https://`. = Header metadata section {parent=Header} OurBigBook adds some header metadata to the toplevel header at the bottom of each page. This section describes this metadata. Although the
{child} has a macro to specify its placement, it is also automatically placed at the bottom of the page, and could be considered a header metadata section. = Incoming links {parent=Header metadata section} Lists other sections that link to the current section. E.g. in: `` = tmp == tmp 1 === tmp 1 1 === tmp 1 2 \x[tmp-1] == tmp 2 \x[tmp-1] `` the page `tmp-1.html` would contain a list of incoming links as: * `tmp-1-2` * `tmp-2` since those pages link to the `tmp-1` ID. = Tagged {parent=Header metadata section} Lists sections that are of the current section, i.e. tagged under the current section. The main header tree hierarchy descendants already show under the
instead. E.g. in: `` = tmp == Mammal == Flying == Animal === Bat {tag=mammal} {tag=flying} === Bee {tag=flying} === Dog {tag=mammal} `` the tagged sections for: * Mammal will contain Bat and Dog * Flying will contain Bat and Bee = Ancestors {parent=Header metadata section} Shows a list of ancestors of the page. E.g. in: `` = Asia == China === Beijing ==== Tiananmen Square === Hong Kong `` the ancestor lists would be for: * Hong Kong: China, Asia * Tiananmen Square: Beijing, China, Asia * Beijing: China, Asia * China: Asia so we see that this basically provides a type of breadcrumb navigation. = Image {parent=Macro} {title2=`\Image` and `\image`} = `\Image` macro {synonym} A block image with [capital] 'i' `Image` showcasing most of the image properties . \OurBigBookExample[[ Have a look at this amazing image: \x[image-my-test-image]. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=The title of my image} {id=image-my-test-image} {width=600} {height=200} {source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg} {description=The description of my image.} ]] This exemplifies the following parameters: * `title`: analogous to the <\H title argument>. Shows up preeminently, and sets a default ID if one is not given. It is recommended that you don't add a period `.` to it, as that would show in * * [`source`]: a standardized way to credit an image by linking to a URL that contains further image metadata For further discussion on the effects of ID see: {full}. And this is how you make an inline image inline one with lower case `i`: \OurBigBookExample[[My inline \image[Tank_man_standing_in_front_of_some_tanks.jpg][test image] is awesome.]] Inline images can't have captions. And now for an image outside of <\OurBigBookExample> to test how it looks directly under : {full}. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {id=image-my-test-image-toplevel} = Image ID {parent=Image} Here is an image without a [description] but with an ID so we can link to it: . \OurBigBookExample[[ Have a look at this amazing image: \x[image-my-test-image-2]. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {id=image-my-test-image-2} ]] This works because <\x full argument>[`full` is the default cross reference style for `Image`], otherwise the link text would be empty since there is no `title`, and OurBigBook would raise an error. OurBigBook can optionally deduce the title from the basename of the `src` argument if the `titleFromSrc` is given, or if `title-from-src` is set as the default [media provider] for the media type: \OurBigBookExample[[ Have a look at this amazing image: \x[image-tank-man-standing-in-front-of-some-tanks]. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {titleFromSrc} ]] = Image caption {parent=Image ID} If the image has neither [ID] nor title nor [description] nor `source`, then it does not get a caption at all: \OurBigBookExample[[\Image[Tank_man_standing_in_front_of_some_tanks.jpg\]]] If the image does not have an ID nor title, then it gets an automatically generated ID, just like every other OurBigBook output HTML element, and it is possible for readers to link to that ID on the rendered version, e.g. as: `` #_123 `` Note that the `123` is not linked to the `Figure .`, but just a sequential ID that runs over all elements. This type of ID is of course not stable across document revisions however, since if an image is added before that one, the link will break. So give an ID or title for anything that you expect users to link to. Also, it is not possible to link to such images with an , like any other OurBigBook element with autogenerated temporary IDs. Another issue to consider is that in paged output formats like PDF, the image could float away from the text that refers to the image, so you basically always want to refer to image by ID, and not just by saying "the following image". We can also see that such an image does not increment the Figure count: \OurBigBookExample[[ \Image[Tank_man_standing_in_front_of_some_tanks.jpg]{id=image-my-test-image-count-before} \Image[Tank_man_standing_in_front_of_some_tanks.jpg] \Image[Tank_man_standing_in_front_of_some_tanks.jpg]{id=image-my-test-image-count-after} ]] If the image has any visible metadata such as `source` or `description` however, then the caption does show and the Figure count gets incremented: \OurBigBookExample[[ \Image[Tank_man_standing_in_front_of_some_tanks.jpg]{source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg} \Image[Tank_man_standing_in_front_of_some_tanks.jpg]{description=This is the description of my image.} ]] = Where to store images {parent=Image} = Store images inside the repository itself {parent=Where to store images} If you are making a limited repository that will not have a ton of images, then you can get away with simply git tracking your images in the main repository. With this setup, no further action is needed. For example, with a file structure of: `` ./README.bigb ./Tank_man_standing_in_front_of_some_tanks.jpg `` just use the image from `README.bigb` as: \OurBigBookExample[[ \Image[Tank_man_standing_in_front_of_some_tanks.jpg] ]] However, if you are making a huge tutorial, which can have a huge undefined number of images (i.e. any scientific book), then you likely don't want to git track your images in the git repository. A generally better alternative is to , and especially . = Store images in a separate media repository {parent=Where to store images} In this approach, you create a separate GitHub repository in addition to the main one containing the text to contain only media such as images. This approach is more suitable than if you are going to have a lot of images. When using this approach, you could of course just point directly to the final image URL, e.g. as in: \OurBigBookExample[[ \Image[https://raw.githubusercontent.com/ourbigbook/ourbigbook-media/master/Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png] ]] but OurBigBook allows you use configurations that allow you to enter just the image basename: `Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png` which we will cover next. In order to get this to work, the recommended repository setup is: * `./main-repo/.git`: main repository at https://github.com/username/main-repo * `./main-repo/data/media/.git/`: media repository at https://github.com/username/main-repo-media[], and where `data/` is gitignored. The directory and repository names are not mandatory, but if you place media in `data/media` and name its repository by adding the `*-media` suffix, then `ourbigbook` will handle everything for you without any further configuration in . This particular documentation repository does have a different setup as can be seen from its \a[ourbigbook.json]. Then, when everything is setup correctly, we can refer to images simply as: \OurBigBookExample[[ \Image[Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png]{provider=github} ]] In this example, we also needed to set `{provider=github}` explicitly since it was not set as the default image provider in our `ourbigbook.json`. In most projects however, all of your images will be in the default repository, so this won't be needed. `provider` must not be given when a full URL is given because we automatically detect providers from URLs, e.g.: `` \Image[https://raw.githubusercontent.com/ourbigbook/ourbigbook-media/master/Fundamental_theorem_of_calculus_topic_page.png]{provider=github} `` is an error. TODO implement: `ourbigbook` will even automatically add and push used images in the `my-tutorial-media` repository for you [during publishing]! You should then use the following rules inside `my-tutorial-media`: * give every file a very descriptive and unique name as a full English sentence * never ever delete any files, nor change their content, unless it is an improvement in format that does change the information contained of the image TODO link to nice Wikimedia Commons guideline page This way, even though the repositories are not fully in sync, anyone who clones the latest version of the `*-media` directory will be able to view any version of the main repository. Then, if one day the media repository ever blows up GitHub's limit, you can just migrate the images to another image server that allows arbitrary basenames, e.g. AWS, and just configure your project to use that new media base URL with the option. The reason why images should be kept in a separate repository is that images are hundreds or thousands of times larger than hand written text. Therefore, images could easily fill up the maximum repository size you are allowed: https://webapps.stackexchange.com/questions/45254/file-size-and-storage-limits-on-github#84746 and then what will you do when GitHub comes asking you to reduce the repository size? https://git-lfs.github.com/[Git LFS] is one approach to deal with this, but we feel that it adds too much development overhead. = Store images in a separate media repository and track it as a git submodule {parent=Store images in a separate media repository} This is likely the sanest approach possible, as it clearly specifies which media version matches which repository version through the submodule link. Furthermore, it is possible to make the submodule clone completely optional by setting things up as follows. For your OurBigBook project `yourname/myproject` create a `yourname/myproject-media` with the media, and track it as a submodule under `yourname/myproject/media`. Then, add to : `` "media-providers": { "github": { "default-for": ["image", "video"], "path": "media", "remote": "yourname/myproject-media" } } `` Now, as mentioned at , everything will work beautifully: * `ourbigbook .` local conversion will use images from `media/` if it exists, e.g.: `` \Image[myimage.jpg] `` will render `media/myimage.jpg`. So after cloning the submodule, you will be able to see the images on the rendered pages without an internet connection. But if the submodule is not cloned, not problem, renders will detect that and automatically use GitHub images. Then, when you do: `` ourbigbook --publish `` the following happen: * `\Image[myimage.jpg]` uses the GitHub URL * automatically push `media/` to GitHub in case there were any updates * also, that directory is automatically gitignore, so it won't be pushed as part of the main render and thus duplicate things = Store images in Wikimedia Commons {parent=Where to store images} Wikimedia Commons is another great possibility to upload your images to: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/Gel_electrophoresis_insert_comb.jpg/450px-Gel_electrophoresis_insert_comb.jpg] {source=https://commons.wikimedia.org/wiki/File:Gel_electrophoresis_insert_comb.jpg} ]] OurBigBook likes Wikimedia Commons so much that we automatically parse the image URL and if it is from Wikimedia Commons, automatically deduce the `source` for you. So the above image renders the same without the `source` argument: \OurBigBookExample[[\Image[https://upload.wikimedia.org/wikipedia/commons/5/5b/Gel_electrophoresis_insert_comb.jpg\]]] And like for non-Wikimedia images, you can automatically generate a `title` from the `src` by setting the `titleFromSrc` or if `title-from-src` is set as the default [media provider] for the media type: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/5/5b/Gel_electrophoresis_insert_comb.jpg] {titleFromSrc} ]] And a quick test for a more complex thumb resized URL: \OurBigBookExample[[\Image[https://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/Gel_electrophoresis_insert_comb.jpg/450px-Gel_electrophoresis_insert_comb.jpg\]]] If you really absolutely want to turn off the `source`, you can explicitly set: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/5/5b/Gel_electrophoresis_insert_comb.jpg] {source=} ]] but you don't want to do that for the most commonly Wikimedia Commons used license of CC BY+, do you? :-) Upsides of using Wikimedia Commons for your images: * makes it easier for other writers to find and reuse your images * automatically generates resized versions of the uploaded images into several common dimensions so you can pick the smallest one that fits your desired to reduce bandwidth usage * if you have so many images that they would blow even the size of a [separate media repository], this will still work Downsides: * forces you to use the Creative Commons license * requires the content to be educational in nature * uploading a bunch of images to Wikimedia Commons does feel a bit more laborious than it should because you have to write down so much repeated metadata for them = Image lazy loading {parent=Image} We do this by default because OurBigBook is meant to allow producing huge single page documents like Ciro likes it, and in this way: * images that the user is looking at will load first * we save a lot of bandwidth for the user who only wants to browse one section TODO: maybe create a mechanism to disable this for the entire build with . = Background color of transparent images {parent=Image} For the love of God, there is no standardized for SVG to set its background color without a rectangle? https://stackoverflow.com/questions/11293026/default-background-color-of-svg-root-element `viewport-fill` was just left in limbo? And as a result, many many many SVG online images that you might want to reuse just rely on white pages and don't add that background rectangle. Therefore for now we just force white background on [our default CSS], which is what most SVGs will work with. Otherwise, you can lose the entire image to our default black background. Then if someone ever has an SVG that needs another background color, we can add an image attribute to set that color as a local style. = Image generators {parent=Image} TODO implement: mechanism where you enter a textual description of the image inside the code body, and it then converts to an image, adds to the `-media` repo and pushes all automatically. Start with dot. https://github.com/ourbigbook/ourbigbook/issues/40 = Image argument {parent=Image} = Image `border` argument {parent=Image argument} {tag=Named argument} {tag=Boolean argument} Adds a border around the image. This can be useful to make it clearer where images start and end when the image background color is the same as the background color of the OurBigBook document. \OurBigBookExample[[ \Image[logo.svg] {border} {height=150} {title=Logo of the OurBigBook Project with a border around it.} ]] = Image `description` argument {parent=Image argument} {tag=`description` argument} {tag=Named argument} The `description` argument similar to the argument, but allows allowing longer explanations without them appearing in to the image. For example, consider: \OurBigBookExample[[ See this image: \x[image-description-argument-test-1]. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=Tank man standing in front of some tanks} {id=image-description-argument-test-1} {description=Note how the tanks are green.} {source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg} ]] In this example, the reference `\x[image-description-argument-test-1]` expands just to \Q[Tank man standing in front of some tanks] and does not include the description, which only shows on the image. The description can be as large as you like. If it gets really large however, you might want to consider moving the image to its own header to keep things slightly saner. This will be especially true after we eventually do: https://github.com/ourbigbook/ourbigbook/issues/180[]. If the description contains any element that would take its own separate line, like multiple paragraphs or a list, we automatically add a line grouping the description with the corresponding image to make that clearer, otherwise it can be hard to know which title corresponds to a far away image. Example with multiple paragraphs: \OurBigBookExample[[ Stuff before the image. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=Tank man standing in front of some tanks} {id=image-description-argument-test-2} {source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg} {description=Note how the tanks are green. But the shirt is white.} Stuff after the image description. ]] We recommend adding a period or other punctuation to the end of every description. = Image `external` argument {parent=Image argument} {tag=Named argument} {tag=Boolean argument} Analogous to the <\a external argument> when checking if the exists or not. = Image `height` argument {parent=Image argument} = Image height {synonym} By default, we fix image heights to `height=315`, and let the `width` be calculated proportionally once the image loads. We therefore ignore the actual image size. This is done to: * prevent reflows as the page loads images and can determine their actual sizes, especially is the user opens the page at a given ID in the middle of the page * create a more uniform media experience by default, unless a custom image size is actually needed e.g. if the image needs to be larger When the [viewport is narrow enough], mobile CSS takes over and forces images to fill 100% of the page width instead. \OurBigBookExample[[ \Image[logo.svg] {height=150} ]] \OurBigBookExample[[ \Image[logo.svg] {height=550} ]] Here's a very long test image: \Image[https://upload.wikimedia.org/wikipedia/commons/4/45/Qian_Xuan_-_Early_Autumn.jpg] {title=Very long test image.} {description=And some tall inline maths: $a_b$.} {height=600} = Image `link` argument {parent=Image argument} {tag=Named argument} If given, make clicking an image go to the specified URL rather than the image's URL as is the default. By default, clicking on a rendered image links to the URL of the image itself. E.g. clicking: \OurBigBookExample[[ \Image[Tank_man_standing_in_front_of_some_tanks.jpg] ]] would open \a[Tank_man_standing_in_front_of_some_tanks.jpg] as produces `img` surrounded by something like `a href="Tank_man_standing_in_front_of_some_tanks.jpg"`. If insetad we want the image to point to a custom URL, e.g. https://ourbigbook.com[] we could instead write: \OurBigBookExample[[ \Image[Tank_man_standing_in_front_of_some_tanks.jpg]{link=https://ourbigbook.com} ]] and now clicking the image leads to https://ourbigbook.com[] instead. = Image `source` argument {parent=Image argument} {tag=Named argument} Where the image was taken from, e.g.: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/6/68/Akha_cropped_hires.JPG] {title=A couple} {source=https://en.wikipedia.org/wiki/Human} ]] The `source` is automatically inferred for certain known websites, e.g.: * Wikimedia `https://upload.wikimedia.org/wikipedia/commons` * from: https://upload.wikimedia.org/wikipedia/commons/6/68/Akha_cropped_hires.JPG * to: https://en.wikipedia.org/wiki/File:Akha_cropped_hires.JPG Example: \OurBigBookExample[[ \Image[https://upload.wikimedia.org/wikipedia/commons/6/68/Akha_cropped_hires.JPG] {title=A couple no source} ]] = Image `src` argument {parent=Image argument} {tag=Positional argument} The address of the image, e.g. in: `` \Image[image.png] `` the `src` is `image.png`. Analogous to the <\a href argument>. = Image `title` argument {parent=Image argument} {tag=`title` argument} Analogous to the <\H title argument>. = Include {parent=Macro} {title2=`\Include`} The `\Include` macro allows including an external OurBigBook headers under the current header. It exists to allow optional single page HTML output while still retaining the ability to: * split up large input files into multiple files to make renders faster during document development * suggest an optional custom output split with one HTML output per OurBigBook input, in order to avoid extremely large HTML pages which could be slow to load `\Include` takes one mandatory argument: the ID of the section to be included, much like . There is however one restriction: only can be pointed to. This restriction allows us to easily find the included file in the filesystem, and dispenses the need to do a first `./ourbigbook` run to generate the [ID database]. This works because . Headers of the included document are automatically shifted to match the level of the child of the level where they are being included. If <--embed-includes> is given, the external document is rendered embedded into the current document directly, essentially as if the source had been copy pasted (except for small corrections such as the header offsets). Otherwise, the following effects happen: * The headers of the included tree appear in the
of the document as links to the corresponding external files. This is implemented simply by reading a previously generated database file much like , which avoids the slowdown of parsing all included files every time. As a result, you have to do an initial parse of all files in the project to extract their headers however, just as you would need to do when linking to those headers. * the include itself renders as a link to the included document * <--embed-includes> Here is an example of inclusion of the files `not-readme.bigb` and `not-readme-2.bigb`: `` \Include[not-readme] \Include[not-readme-2] \Include[not-readme-with-scope] `` The above is the recommended and slightly [insaner] version of: `` \Include[not-readme] \Include[not-readme-2] \Include[not-readme-with-scope] `` The insaner version is a bit insaner because the `\Include` magically discards the following newline node that follows it if it just a plaintext node containing exactly a newline. With a double newline, the newline would already have been previously taken out on the lexing stage as part of a paragraph. <\Include example>{full} shows what those actually render like. = `\Include` from subdirectories {parent=Include} When you are in a subdirectory, include resolution just is simply relative to the subdirectory. E.g. we could do: subdir/index.bigb `` = Subdir \Include[notindex] \Include[subdir2/notindex] `` subdir/notindex.bigb `` = Notindex `` subdir/subdir2/notindex.bigb `` = Notindex `` It is not currently possible to include from ancestor directories: https://github.com/ourbigbook/ourbigbook/issues/214[]. = `\Include` `parent` argument {parent=Include} This option is analogous to <\H parent argument>, but for . For example, consider you have: `` = Animal == Dog == Cat == Bat `` and now you want to split `Cat` to `cat.bigb`. If you wrote: `` = Animal == Dog \Include[cat] == Bat `` Cat would be a child of Dog, since that is the previous header, which is not what we want. Instead, we want to write: `` = Animal == Dog \Include[cat]{parent=animal} == Bat `` and now Cat will be a child of Animal as desired. Implemented at: https://github.com/ourbigbook/ourbigbook/issues/127 = `\Include` example {parent=Include} This shows what includes render as. \Include[not-readme] \Include[not-readme-2] \Include[not-readme-with-scope] \Include[subdir] \Include[subdir/notindex] = Italic {parent=Macro} {title2=`\i`} = `\i` macro {synonym} \OurBigBookExample[[Some \i[italic] text.]] = `\JsCanvasDemo` {parent=Macro} The `JsCanvasDemo` macro allows you to create interactive HTML/JavaScript https://en.wikipedia.org/wiki/Canvas_element[canvas] demos easily. These demos: * only start running when the user scrolls over them for the first time * stop automatically when they leave the viewport so you can stuff as many of them as you want on a page, and they won't cause the reader's CPU to fry an egg. \OurBigBookExample[[[ \JsCanvasDemo[[ new class extends OurbigbookCanvasDemo { init() { super.init('hello'); this.pixel_size_input = this.addInputAfterEnable( 'Pixel size', { 'min': 1, 'type': 'number', 'value': 1, } ); } draw() { var pixel_size = parseInt(this.pixel_size_input.value); for (var x = 0; x < this.width; x += pixel_size) { for (var y = 0; y < this.height; y += pixel_size) { var b = ((1.0 + Math.sin(this.time * Math.PI / 16)) / 2.0); this.ctx.fillStyle = 'rgba(' + (x / this.width) * 255 + ',' + (y / this.height) * 255 + ',' + b * 255 + ',255)' ; this.ctx.fillRect(x, y, pixel_size, pixel_size); } } } } ]] ]]] And another one showing off some https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API[WebGL]: \JsCanvasDemo[[ new class extends OurbigbookCanvasDemo { init() { super.init('webgl', {context_type: 'webgl'}); this.ctx.viewport(0, 0, this.ctx.drawingBufferWidth, this.ctx.drawingBufferHeight); this.ctx.clearColor(0.0, 0.0, 0.0, 1.0); this.vertexShaderSource = ` #version 100 precision highp float; attribute float position; void main() { gl_Position = vec4(position, 0.0, 0.0, 1.0); gl_PointSize = 64.0; } `; this.fragmentShaderSource = ` #version 100 precision mediump float; void main() { gl_FragColor = vec4(0.18, 0.0, 0.34, 1.0); } `; this.vertexShader = this.ctx.createShader(this.ctx.VERTEX_SHADER); this.ctx.shaderSource(this.vertexShader, this.vertexShaderSource); this.ctx.compileShader(this.vertexShader); this.fragmentShader = this.ctx.createShader(this.ctx.FRAGMENT_SHADER); this.ctx.shaderSource(this.fragmentShader, this.fragmentShaderSource); this.ctx.compileShader(this.fragmentShader); this.program = this.ctx.createProgram(); this.ctx.attachShader(this.program, this.vertexShader); this.ctx.attachShader(this.program, this.fragmentShader); this.ctx.linkProgram(this.program); this.ctx.detachShader(this.program, this.vertexShader); this.ctx.detachShader(this.program, this.fragmentShader); this.ctx.deleteShader(this.vertexShader); this.ctx.deleteShader(this.fragmentShader); if (!this.ctx.getProgramParameter(this.program, this.ctx.LINK_STATUS)) { console.log('error ' + this.ctx.getProgramInfoLog(this.program)); return; } this.ctx.enableVertexAttribArray(0); var buffer = this.ctx.createBuffer(); this.ctx.bindBuffer(this.ctx.ARRAY_BUFFER, buffer); this.ctx.vertexAttribPointer(0, 1, this.ctx.FLOAT, false, 0, 0); this.ctx.useProgram(this.program); } draw() { this.ctx.clear(this.ctx.COLOR_BUFFER_BIT); this.ctx.bufferData(this.ctx.ARRAY_BUFFER, new Float32Array([Math.sin(this.time / 60.0)]), this.ctx.STATIC_DRAW); this.ctx.drawArrays(this.ctx.POINTS, 0, 1); } } ]] = List {parent=Macro} {title2=`* `, `\L`, `\Ul`, `\Ol`} with `* ` (asterisk space): \OurBigBookExample[[ * a * b * c ]] Equivalent saner with [implicit `ul` container]: \OurBigBookExample[[ \L[a] \L[b] \L[c] ]] Equivalent fully sane with explicit container: \OurBigBookExample[[ \Ul[ \L[a] \L[b] \L[c] ] ]] The explicit container is required if you want to pass extra arguments properties to the `ul` list macro, e.g. a title and an ID: {full}: \OurBigBookExample[[ \Ul {id=list-my-id} [ \L[a] \L[b] \L[c] ] ]] This is the case because without the explicit container in an implicit `ul` list, the arguments would stick to the last list item instead of the list itself. It is also required if you want ordered lists: \OurBigBookExample[[ \Ol[ \L[first] \L[second] \L[third] ] ]] Insane nested list with two space indentation: \OurBigBookExample[[ * a * a1 * a2 * a2 * b * c ]] The indentation must always be exactly equal to two spaces, anything else leads to errors or unintended output. Equivalent saner nested lists with implicit containers: \OurBigBookExample[[ \L[ a \L[a1] \L[a2] \L[a2] ] \L[b] \L[c] ]] Insane list item with a paragraph inside of it: \OurBigBookExample[[ * a * I have Multiple paragraphs. * And * also * a * list * c ]] Equivalent sane version: \OurBigBookExample[[ \L[a] \L[ I have Multiple paragraphs. \L[And] \L[also] \L[a] \L[list] ] \L[c] ]] Insane lists may be escaped with a backslash as usual: \OurBigBookExample[[\* paragraph starting with an asterisk.]] You can also start insane lists immediately at the start of a [positional or named argument], e.g.: \OurBigBookExample[[ \P[* a * b * c ] ]] And now a list outside of <\OurBigBookExample> to test how it looks directly under : * a * b * c = Mathematics {parent=Macro} {title2=`$$`, `$`, `\M`, `\m`} Via https://katex.org/[KaTeX] server side, oh yes! Inline math is done with the dollar sign (`$`) : \OurBigBookExample[[My inline $\sqrt{1 + 1}$ is awesome.]] and block math is done with two or more dollar signs (`$$`): \OurBigBookExample[[ $$ \sqrt{1 + 1} \\ \sqrt{1 + 1} $$ ]] The sane version of inline math is a lower case `m`: \OurBigBookExample[[[My inline \m[[\sqrt{1 + 1}]] is awesome.]]] and the sane version of block math is with an upper case `M`: \OurBigBookExample[[[ \M[[ \sqrt{1 + 1} \\ \sqrt{1 + 1} ]] ]]] The capital vs lower case theme is also used in other elements, see: . In the sane syntax, [as with any other argument], you have to either escape any closing square brackets `]` with a backslash `\`: \OurBigBookExample[[My inline \m[1 - \[1 + 1\] = -1] is awesome.]] or with the equivalent double open and close: `` My inline \m[[1 - [1 + 1] = -1]] is awesome. `` HTML escaping happens as you would expect, e.g. `<` shows fine in: \OurBigBookExample[[ $$ 1 < 2 $$ ]] Equation IDs and titles and linking to equations works identically to , see that section for full details. Here is one equation reference example that links to the following insane syntax equation: : \OurBigBookExample[[ $$ \sqrt{1 + 1} $$ {title=My first insane equation} ]] and the sane equivalent : \OurBigBookExample[[[ \M{title=My first sane equation}[[ \sqrt{1 + 1} ]] ]]] Here is a raw one just to test the formatting outside of a `ourbigbook_comment`: $$ \sqrt{1 + 1} $$ Here is a very long math equation: $$ Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello \\ HelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHello \\ Hello $$ = `\M` argument {c} {parent=Mathematics} = `\M` `description` argument {parent=`\M` argument} {tag=`description` argument} See: <`description` argument>{full}. \OurBigBookExample[[ See the: . $$ c = \sqrt{a^2 + b^2} $$ {title=Pytogoras theorem} {description=This important equation allows us to find the distance between two points.} ]] = `\M` `title` argument {parent=`\M` argument} {tag=`title` argument} See: <`title` argument>{full}. Example: \OurBigBookExample[[ See the: . $$ \zeta(s) = \sum_{n=1}^\infty \frac{1}{n^s} $$ {title=Riemann zeta function} ]] = LaTeX macros {c} {parent=Mathematics} = Math macros {synonym} = Built-in LaTeX macros {parent=LaTeX macros} = Built-in math macros {synonym} OurBigBook ships with several commonly used math macros enabled by default. The full list of built-in macros can be seen at: \a[default.tex]. Here's one example of using `\dv` from the http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/physics/physics.pdf[`physics` package] for derivatives: \OurBigBookExample[[ $$ \dv{x^2}{x} = 2x $$ ]] Our goal is to collect the most popular macros from the most popular pre-existing LaTeX packages and make them available with this mechanism. The built-in macros are currently only available on and , not when using the directly. We should likely make that possible as well at some point. = User-defined LaTeX macros {parent=LaTeX macros} = User-defined macros {synonym} = `ourbigbook.tex` {parent=User defined LaTeX macros} If your project has multiple `.bigb` input files, you can share Mathematics definitions across all files by adding them to the `ourbigbook.tex` file on the toplevel directory. For example, if `ourbigbook.tex` contains: `` \newcommand{\foo}[0]{bar} `` then from any `.bigb` file we in the project can use: `` $$ \foo $$ `` Note however that this is not portable to and will likely never be, as we want Web source to be reusable across authors. So the ony way to avoid macro definition conflicts would be to have a namespace system in place, which sounds hard/impossible. Ideally, you should only use this as a temporary mechanism while you make a pull request to modify the :-) = Inline user-defined LaTeX macros {parent=User-defined LaTeX macros} = Math defines across blocks {synonym} Besides using , you can also define your own math macros directly in the source code. This is generally fragile however because it doesn't work: * across on * across different source files on . That can be worked around with on CLI, but does not work on Web either. If you still want to do it for some reason, first create an invisible block (with `{show=0}`) defining with a `\newcommand` definition: \OurBigBookExample[[ $$ \newcommand{\foo}[0]{bar} $${show=0} ]] We make it invisible because this block only contains KaTeX definitions, and should not render to anything. Then the second math block uses those definitions: \OurBigBookExample[[ $$ \foo $$ ]] Analogously with `\def`, definition: \OurBigBookExample[[ $$ \gdef\foogdef{bar} $${show=0} ]] and the second block using it: \OurBigBookExample[[ $$ \foogdef $$ ]] And just to test that `{show=1}` actually shows, although it is useless, and that `{show=0}` skips incrementing the equation count: \OurBigBookExample[[ $$1 + 1$${show=1} $$2 + 2$${show=0} $$3 + 3$${show=1} ]] = `\OurBigBookExample` {parent=Macro} Shows both the OurBigBook code and its rendered output, e.g.: \OurBigBookExample[[[ \OurBigBookExample[[ Some `ineline` code. ]] ]]] Its input should be thought of as a literal code string, and it then injects the rendered output in the document. This macro is used extensively in the OurBigBook documentation. = Paragraph {parent=Macro} {title2=`\P`} OK, this is too common, so we opted for some here: double newline is a paragraph! \OurBigBookExample[[ Paragraph 1. Paragraph 2. ]] Equivalently however, you can use an explicit `\P` macros as well, which is required for example to add properties to a paragraph, e.g.: \OurBigBookExample[[ \P{id=paragraph-1}[Paragraph 1] \P{id=paragraph-2}[Paragraph 2] ]] Paragraphs are created automatically inside whenever a double newline appears. Note that OurBigBook paragraphs render in HTML as `div` with `class="p"` and not as `p`. This means that you can add basically anything inside them, e.g. a list: `` My favorite list is: \Ul[ \li[aa] \li[bb] ] because it is simple. `` which renders as a single paragraph. One major advantage of this, is that when writing documentation, you often want to keep lists or code blocks inside a given paragraph, so that it is easy to reference the entire paragraph with an ID. Think for example of paragraphs in the C++ standard. = Passthrough {parent=Macro} {title2=`\passthrough`} Dumps its contents directly into the rendered output. This construct is not XSS safe, see: {full}. Here for example we define a paragraph in raw HTML: \OurBigBookExample[[[ \passthrough[[

Hello raw HTML!

]] ]]] And for an inline passthrough: \OurBigBookExample[[[Hello \passthrough[[raw]] world!]]] = Quotation {parent=Macro} {title2=`\Q`} With `q`: \OurBigBookExample[[ And so he said: \Q[ Something very smart And with multiple paragraphs. ] and it was great. ]] = `\Q` argument {parent=Quotation} = `\Q` `description` argument {parent=`\Q` argument} {tag=`description` argument} See: <`description` argument>{full}. Example: \OurBigBookExample[[ See the: . \Q[We know what we are, but not what we may be.] {title=Hamlet what we are} {description=This quote refers to human's inability to know their own potential, despite understanding their current abilities.} ]] = `\Q` `title` argument {parent=`\Q` argument} {tag=`title` argument} See: <`title` argument>{full}. Example: \OurBigBookExample[[ See the: . \Q[The fault, dear Brutus, is not in our stars, but in ourselves.] {title=Julius Caesar star} ]] = Table {parent=Macro} {title2=`|| `, `| `, `\Table`, `\Tr`, `\Th` and `\Td`} The marks: * headers with `|| ` (pipe, pipe space) at the start of a line * regular cells with `| ` (pipe, space) at the start of a line * separates rows with double newline For example: \OurBigBookExample[[ || Header 1 || Header 2 | 1 1 | 1 2 | 2 1 | 2 2 ]] Empty cells are allowed without the trailing space however: \OurBigBookExample[[ | 1 1 | | 1 3 | 2 1 | | 2 3 ]] Equivalent fully explicit version: \OurBigBookExample[[ \Table[ \Tr[ \Th[Header 1] \Th[Header 2] ] \Tr[ \Td[1 1] \Td[1 2] ] \Tr[ \Td[2 1] \Td[2 2] ] ] ]] Any white space indentation inside an explicit `\Tr` can make the code more readable, and is automatically removed from final output due to which is set for `\Table`. To pass further arguments to an implicit table such as `title` or `id`, you need to use an explicit `table` macro as in:
. \OurBigBookExample[[ \Table {title=My table title} {id=table-my-table} [ || Header 1 || Header 2 | 1 1 | 1 2 | 2 1 | 2 2 ] ]] We would like to remove that explicit toplevel requirement as per: https://github.com/ourbigbook/ourbigbook/issues/186[] The rules of when the caption shows up or not similar to those of as mentioned at {full}. Multiple source lines, including paragraphs, can be added to a single cell with insane syntax by indenting the cell with exactly two spaces just as for , e.g.: \OurBigBookExample[[ || h1 || h2 || h3 h3 2 | 11 | 12 12 2 | 13 | 21 | 22 | 23 ]] Arbitrarily complex nested constructs may be used, e.g. a table inside a list inside table: \OurBigBookExample[[ | 00 | 01 * l1 * l2 | 20 | 21 | 30 | 31 | 10 | 11 ]] And now a table outside of <\OurBigBookExample> to test how it looks directly under : \Table[ || Header 1 || Header 2 | 1 1 | 1 2 | 2 1 | 2 2 ] {title=My table title} And a fully insane one: || Header 1 || Header 2 | 1 1 | 1 2 | 2 1 | 2 2 = Table sorting {parent=Table} JavaScript interactive on-click table sorting is enabled by default, try it out by clicking on the header row: \OurBigBookExample[[ || String col || Integer col || Float col | ab | 2 | 10.1 | a | 10 | 10.2 | c | 2 | 3.4 ]] Powered by: https://github.com/tristen/tablesort = `\Table` argument {parent=Table} = `\Table` `description` argument {parent=`\Table` argument} {tag=`description` argument} See: <`description` argument>{full}. = `\Table` `title` argument {parent=`\Table` argument} {tag=`title` argument} See: <`title` argument>{full}. = Table of contents {parent=Macro} {title2=ToC} OurBigBook automatically adds a table of contents at the end of the first [non-toplevel header] of every document. For example, on a standard document with a single toplevel header: `` = Animal Animals are cute! == Dog == Cat `` the ToC is rendered something like: `` = Animal Animals are cute! Table of Contents * Dog * Cat == Dog == Cat `` The ToC ignores if you have one. For when you want a quick outline of the header tree on the terminal, also consider the <--log headers> option. = Table of contents JavaScript open close interaction {parent=Table of contents} To the left of table of content entries you can click on an open/close icon to toggle the visibility of different levels of the table of contents. The main use case covered by the expansion algorithm is as follows: * the page starts with all nodes open to facilitate Ctrl + F queries * if you click on a node in that sate, you close all its children, to get a summarized overview of the contents * if you click one of those children, it opens only its own children, so you can interactively continue exploring the tree The exact behaviour is: * the clicked node is open: * state 1 all children are closed. Action: open all children recursively, which puts us in state 2 * state 2: not all children are closed. Action close all children, which puts us in state 1. This gives a good overview of the children, without any children of children getting in the way. * state 3: the clicked node is closed (not showing any children). Action: open it to show all direct children, but not further descendants (i.e. close those children). This puts us in state 1. Note that those rules make it impossible to close a node by clicking on it, the only way to close a node os to click on its parent, the state transitions are: * 3 -> 1 * 1 -> 2 * 2 -> 1 but we feel that it is worth it to do things like this to cover the main use case described above without having to add two buttons per entry. Clicking on the link from a
up to the table of contents also automatically opens up the node for you in case it had been previously closed manually. = Video {parent=Macro} {title2=`\Video`} Very analogous to , only differences will be documented here. In the case of videos, becomes even more critical since videos are even larger than images, such that the following storage approaches are impractical off the bat: * * As a result, then https://commons.wikimedia.org[Wikimedia Commons] is one of the best options [much like for images]: \OurBigBookExample[[ \Video[https://upload.wikimedia.org/wikipedia/commons/8/85/Vacuum_pump_filter_cut_and_place_in_eppendorf.webm] {id=sample-video-in-wikimedia-commons} {title=Nice sample video stored in Wikimedia Commons} {start=5} ]] We also handle more complex transcoded video URLs just fine: \OurBigBookExample[[ \Video[https://upload.wikimedia.org/wikipedia/commons/transcoded/1/19/Scientific_Industries_Inc_Vortex-Genie_2_running.ogv/Scientific_Industries_Inc_Vortex-Genie_2_running.ogv.480p.vp9.webm] {id=sample-video-in-wikimedia-commons-transcoded} {title=Nice sample video stored in Wikimedia Commons transcoded} ]] Commons is better than YouTube if your content is on-topic there because: * they have no ads * it allows download of the videos: https://www.quora.com/Can-I-download-Creative-Commons-licensed-YouTube-videos-to-edit-them-and-use-them[]. * it makes it easier for other users to find and re-use your videos If your video does not fit the above Wikimedia Commons requirements, YouTube could be a good bet. OurBigBook https://github.com/ourbigbook/ourbigbook/issues/50[automatically detects YouTube URLs] for you, so the following should just work: \OurBigBookExample[[ \Video[https://youtube.com/watch?v=YeFzeNAHEhU&t=38] {id=sample-video-from-youtube-implicit-youtube} {title=Nice sample video embedded from YouTube implicit from `youtube.com` URL} ]] The `youtu.be` domain hack URLs also work; \OurBigBookExample[[ \Video[https://youtu.be/YeFzeNAHEhU?t=38] {id=sample-video-from-youtube-implicit-youtu-be} {title=Nice sample video embedded from YouTube implicit from `youtu.be` URL} ]] Alternatively, you can reach the same result in a more explicit and minimal way by setting `{provider=youtube}` and the <\Video start argument>[`start`] arguments: \OurBigBookExample[[ \Video[YeFzeNAHEhU]{provider=youtube} {id=sample-video-from-youtube-explicit} {title=Nice sample video embedded from YouTube with explicit `youtube` argument} {start=38} ]] When the `youtube` provider is selected, the Video address should only to contain the YouTube video ID, which shows in the YouTube URL for the video as: `` https://www.youtube.com/watch?v= `` Remember that you can also enable the `youtube` provider by default on your with: `` "media-provider" { "youtube": {"default-for": "video"} } `` But you can also use raw video files from any location that can serve them of course, e.g. here is one stored in this repository: . \OurBigBookExample[[ \Video[Tank_man_side_hopping_in_front_of_some_tanks.mp4] {id=sample-video-in-repository} {title=Nice sample video stored in this repository} {source=https://www.youtube.com/watch?v=YeFzeNAHEhU} {start=3} ]] And as for images, setting `titleFromSrc` automatically calculates a title for you: \OurBigBookExample[[ \Video[Tank_man_side_hopping_in_front_of_some_tanks.mp4] {titleFromSrc} {source=https://www.youtube.com/watch?v=YeFzeNAHEhU} ]] = Video lazy loading {parent=Video} Unlike , we don't support video lazy loading yet because: * non-`youtube` videos use the `video` tag which has no `loading` property yet * `youtube` videos are embedded with `iframe` and `iframe` has no `loading` property yet Both of this cases could be worked around with JavaScript: * non-`youtube`: set `src` from JavaScript as shown for images: https://stackoverflow.com/questions/2321907/how-do-you-make-images-load-lazily-only-when-they-are-in-the-viewport/57389607#57389607[]. But this breaks page semantics however, we don't know how to work around that * `youtube` videos: same as above for the `iframe`, but this should be less problematic since YouTube videos are not viewable without JavaScript anyways, and who cares about `iframe` semantics? = `\Video` argument {parent=Video} = `\Video` `description` argument {parent=`\Video` argument} {tag=`description` argument} See: <`description` argument>{full}. = `\Video` `title` argument {parent=`\Video` argument} {tag=`title` argument} See: <`title` argument>{full}. = `\Video` `start` argument {parent=`\Video` argument} The time to start playing the video at in seconds. Works for both `youtube` and non-YouTube videos. = Cross reference {parent=Macro} = Internal cross reference {synonym} = `\x` macro {synonym} {title2} Every macro in OurBigBook can have an optional `id` and many also have a reserved `title` property. When a macro in the document has a `title` argument but no `id` argument given, get an auto-generated ID from the title: . Usually, the most convenient way to write cross references is with the insane syntax with delimited angled braces: \OurBigBookExample[[ are awesome.]] More details at: . The sane equivalent to this is: \OurBigBookExample[[\x[cross-reference]{c}{p} are awesome section.]] Note how that is more verbose, especially because here we use both the <\x c argument> and <\x p argument> to capitalize and pluraize as desired. Another sane equivalent would be to add an explicit link body as in: \OurBigBookExample[[\x[cross-reference][Cross references] are awesome.]] = Insane cross reference {parent=Cross reference} {tag=Insane macro shortcut} {title2=`<>`} When you use an insane cross reference (`<>`) such as in: \OurBigBookExample[[ are awesome.]] it gets expanded exactly to the sane equivalent: `` \x[Cross references]{magic} are alwasome `` so we see that the <\x magic argument> gets added. It is that argument that for example adds the missing `-`, and removes the pluralization to find the correct ID `cross-reference`. For more details, see the documentation of the <\x magic argument>. Like other constructs, are exactly equivalent to the sane version, so you can just add other arguments after the construct, e.g.: \OurBigBookExample[[{full} are awesome.]] which gets converted to exact the same as the sane: \OurBigBookExample[[\x[cross-reference]{full} are awesome.]] = Cross reference title inflection {parent=Cross reference} In most cases it is generally more convenient to simply use the <\x magic argument> through instead of the `c` and `p` arguments as described on the rest of this section, see also: {full}. A common usage pattern is that we want to use
titles in <\x full argument>[non-full] as the definition of a concept without repeating the title, for example: `` == Dog Cute animal. \x[cats][Cats] are its natural enemies. == Cats This is the natural enemy of a \x[dog][dog]. \x[dog][Dogs] are cute, but they are still the enemy. One example of a cat is \x[felix-the-cat]. === Felix the Cat Felix is not really a \x[cats][cat], just a carton character. `` However, word https://en.wikipedia.org/wiki/Inflection[inflection] makes it much harder to avoid retyping the definition again. For example, in the previous example, without any further intelligent behaviour we would be forced to re-type `\x[dog][dog]` instead of the desired `\x[dog]`. OurBigBook can take care of some inflection cases for you. For capitalization, both headers and cross reference macros have the `c` which stands for "capitalized": * for headers, `c` means that the header title has fixed capitalization as given in the title, i.e. * if the title has a capital first character, it will always show as a capital, as is the case for most https://en.wikipedia.org/wiki/Proper_noun[proper noun] * if it is lower case, it will also always remain lower case, as is the case for some rare proper nouns, notably https://en.wikipedia.org/wiki/Arm_Holdings[the name of certain companies] This means that for such headers, `c` in the `x` has no effect. Maybe we should give an error in that case. But lazy now, send PR. * for cross reference macros, `c` means that the first letter of the title should be capitalized. Using this option is required when you are starting a sentence with a non-proper noun. Capitalization is handled by a . For pluralization, cross reference macros have the `p` which stands for "pluralize": * if given and true, this automatically pluralizes the last word of the target title by using the https://github.com/blakeembrey/pluralize library * if given and false, automatically singularize * if not given, don't change the number of elements If your desired pluralization is any more complex than modifying the last word of the title, you must do it manually however. With those rules in mind, the previous OurBigBook example can be written with less repetition as: `` == Dog Cute animal. \x[cats]{c} are its natural enemies. == Cats This is the natural enemy of a \x[dog]. \x[dog]{p} are cute, but they are still the enemy. One example of a cat is \x[Felix the Cat]. === Felix the Cat {c} Felix is not really a \x[cats][cat], just a carton character. `` If plural and capitalization don't handle your common desired inflections, you can also just create custom ones with the <\H synonym argument>. Now for a live example for quick and dirty interactive testing. = Cross reference title inflection example {parent=Cross reference title inflection} \OurBigBookExample[[\x[inflection-example-not-proper\]]] \OurBigBookExample[[\x[inflection-example-not-proper]{c}]] \OurBigBookExample[[\x[inflection-example-not-proper]{full}]] \OurBigBookExample[[\x[inflection-example-proper\]]] \OurBigBookExample[[\x[inflection-example-proper]{c}]] \OurBigBookExample[[\x[inflection-example-not-proper-lower\]]] \OurBigBookExample[[\x[inflection-example-not-proper-lower]{c}]] \OurBigBookExample[[\x[inflection-example-proper-lower\]]] \OurBigBookExample[[\x[not-readme\]]] \OurBigBookExample[[\x[not-readme]{c}]] \OurBigBookExample[[\x[inflection-example-not-proper]{p}]] \OurBigBookExample[[\x[inflection-plural-examples\]]] \OurBigBookExample[[\x[inflection-plural-examples]{p}]] \OurBigBookExample[[\x[inflection-plural-examples]{p=0}]] \OurBigBookExample[[\x[inflection-plural-examples]{p=1}]] \OurBigBookExample[[\x[not-the-readme-header-with-fixed-case\]]] = Inflection example not-proper {parent=Cross reference title inflection example} = Inflection example proper {c} {parent=Cross reference title inflection example} = inflection example not-proper lower {parent=Cross reference title inflection example} = inflection example proper lower {c} {parent=Cross reference title inflection example} = Inflection plural examples {parent=Cross reference title inflection example} = Inflection vs magic {parent=Cross reference} The <\x magic argument> was introduced later, and basically became a better alternative to in all but the following cases: * <\H disambiguate argument>: disambiguate prevents the determination of plural inflection, e.g. in: `` = Python {disambiguate=animal} I like . `` there is currently no way to make it output `Pythons` in the plural without resorting to either <\x p argument> or an explicit content, because if you wrote: `` I like . `` it would just lead to Id not found, as we would try the plural vs singular on `animal` only. Maybe one day we can implement an even insaner system that understands that parenthesis should skipped for the inflection as in: `` I like . `` https://github.com/ourbigbook/ourbigbook/issues/244 * plural headers. We only attempt to singularize arguments for now, not pluralize them. So if you had: `` My is nice. == Dogs `` you would instead need to write: `` My {p=0} is nice. `` or: `` My [dog] is nice. `` = `\x` within `title` restrictions {parent=Cross reference} If you use `\x` within a `title`, which most commonly happens for [image titles], that can generate complex dependencies between IDs, which would either be harder to implement, or lead to infinite recursion. To prevent such problems, OurBigBook emits an error if you use an `\x` without content in the `title` of one of the following elements: * any
. For example, the following gives an error: `` = h1 {id=myh1} == \x[myh1] `` This could be solved by either adding a content to the reference: `` = h1 {id=myh1} == \x[myh1][mycontent] `` or by adding an explicit ID to the header: `` = h1 {id=myh1} == \x[myh1] {id=myh2} `` * non-header (e.g. an ) that links to the title of another non-header For non-headers, things are a bit more relaxed, and we can link to headers, e.g.: `` = h1 \Image[myimg.jpg] {title=my \x[h1]} `` This is allowed because OurBigBook calculates IDs in two stages: first for all headers, and only later non non-headers. What you cannot do is link to another image e.g.: `` \Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {title=my \x[h1]} `` and there the workaround are much the same as for headers: either explicitly set the cross reference content: `` \Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {title=my \x[h1][My image 1]} `` or explicitly set an ID: `` \Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {id=myimage2} {title=my \x[h1]} `` TODO both workaround are currently broken , we forgot to add a test earlier on, and things inevitably broke... Should not be hard to fix though, we are just overchecking. While it is technically possible relax the above limitations and give an error only in case of loops, it would require a bit of extra work which we don't want to put in right now: https://github.com/ourbigbook/ourbigbook/issues/95[]. Furthermore, the above rules do not exclude infinite rendering loops, but OurBigBook detects such loops and gives a nice error message, this has been fixed at: https://github.com/ourbigbook/ourbigbook/issues/34 For example this would contain an infinite loop: `` \Image[myimg.jpg] {id=myimage1} {title=\x[myimage2]} \Image[myimg.jpg] {id=myimage2} {title=\x[myimage1]} `` This infinite recursion is fundamentally not technically solved: the user has to manually break the loop by providing an `x` content explicitly, e.g. in either: `` \Image[myimg.jpg] {id=myimage1} {title=\x[myimage2][my content 2]} \Image[myimg.jpg] {id=myimage2} {title=\x[myimage1]} `` or: `` \Image[myimg.jpg] {id=myimage1} {title=\x[myimage2]} \Image[myimg.jpg] {id=myimage2} {title=\x[myimage1][my content 1]} `` A closely related limitation is the simplistic approach to <\x id output format>. = Cross file reference {parent=Cross reference} = Internal cross file reference {synonym} Reference to the first header of another file: \OurBigBookExample[[\x[not-readme\]]] Reference to a non-first header of another file: \OurBigBookExample[[\x[h2-in-not-the-readme\]]] To make toplevel links cleaner, if the target header is the very first element of the other page, then the link does not get a fragment, e.g.: `\x[not-readme]` rendered as: `` [`full`]: \OurBigBookExample[[\x[h2-in-not-the-readme]{full}.]] Note that when `full` is used with references in another file in <--embed-includes>[multi page mode], the number is not rendered as explained at: <\x full argument in cross file references>{full}. Reference to an image in another file: \OurBigBookExample[[\x[image-not-readme-xi]{full}.]] Reference to an image in another file: \OurBigBookExample[[\x[image-figure-in-not-the-readme-without-explicit-id]{full}.]] Remember that the [ID of the toplevel header] is automatically derived from its file name, that's why we have to use: \OurBigBookExample[[\x[not-readme\]]] instead of: `` \x[not-the-readme] `` Reference to a subdirectory: \OurBigBookExample[[ \x[subdir] \x[subdir/h2] \x[subdir/notindex] \x[subdir/notindex-h2] ]] Implemented at: https://github.com/ourbigbook/ourbigbook/issues/116 Reference to an internal header of another file:

. By default, That header ID gets prefixed by the ID of the top header. When using <--embed-includes> mode, the cross file references end up pointing to an ID inside the current HTML element, e.g.: `` `` rather than: `` `` This is why IDs must be unique for elements across all pages. = Cross file reference internals {parent=Cross file reference} {title2=`db.sqlite3`} = ID database {c} {synonym} When running in Node.js, OurBigBook dumps the IDs of all processed files to a `out/db.sqlite3` file in , and then reads from that file when IDs are needed. When converting under a directory that contains , `out/db.sqlite3` is placed inside the same directory as the `ourbigbook.json` file. If there is no `ourbigbook.json` in parent directories, then `out/db.sqlite3` is placed in the current working directory. These follows the principles described at: . `db.sqlite3` is not created or used when handling input from . When running in the browser, the same JavaScript API will send queries to the server instead of a local SQLite database. To inspect the ID database to debug it, you can use: `` sqlite3 out/db.sqlite3 .dump `` It is often useful to dump a single table, e.g. to dump the `ids` table: `` sqlite3 out/db.sqlite3 '.dump ids' `` and one particularly important query is to dump a list of all known IDs: `` sqlite3 out/db.sqlite3 'select id from ids' `` You can force `ourbigbook` to not use the ID database with the <--no-db> command line option = Link to IDs, not URL path {parent=Cross file reference} This section describes the philosophy of . In many static website generators, you just link to URL specific paths of internal headers. In OurBigBook, point to IDs, not paths. For example, suppose "Superconductivity" is a descendant of "Condensed Matter Physics", and that the source for both is located at `condensed-matter-physics.bigb`, so that both appear on the same .html page `condensed-matter-physics.html`. When linking to Superconductivity from an external page such as `statistical-physics.bigb` you write just `` and NOT ``. OurBigBook then automatically trakcs where superconductivity is located and produces `href="condensed-matter-physics#superconductivity"` for you. This is important because on a static website, the location of headers might change. E.g. if you start writing a lot about superconductivity you would eventually want to split it to its own page, `superconductivity.html` otherwise page loads for `condensed-matter-physics.html` would become too slow as that file would become too large. But if your links read ``, and all links would break when you move things around. So instead, you simply link to the ID ``, and ourbigbook renders links correctly for you wherever the output lands. When moving headers to separate pages, it is true that existing links to subheaders will break, but that simply cannot be helped. Large pages must be split into smaller ones. The issue can be mitigated in the following ways: * , which readers will eventually understand are better permalinks * , which automatically redirect `condensed-matter-physics#superconductivity` to `superconductivity`, potentially hitting a if the current page does not contain the HTML ID `superconductivity`. For , this is even more important, as we have , so every header can appear on top. If you really want to to use scopes, e.g. enforce the ID of "superconductivity" to be "condensed-matter-physics/superconductivity", then you can use the feature. However, this particular case would likely be a bad use case for that feature. You want your IDs to be as short as possible, which causes less need for refactoring, and makes on more likely to have matches from other users. = Cross reference title link removal {parent=Cross file reference} If the target `title` argument contains a link from either another or a regular [external hyperlink], OurBigBook automatically prevents that link from rendering as a link when no explicit body is given. This is done because https://stackoverflow.com/questions/9882916/are-you-allowed-to-nest-a-link-inside-of-a-link[nested links are illegal in HTML], and the result would be confusing. This use case is most common when dealing with media such as . For example in: `` = afds \x[image-aa-zxcv-lolol-bb] == qwer \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=aa \x[zxcv][zxcv] \a[http://example.com][lolol] bb} == zxcv `` the `\x[image-aa-zxcv-lolol-bb]` renders something like: `` aa zxcv lolol bb `` and not: `` aa zxcv lolol bb `` Live example: \OurBigBookExample[[ This is a nice image: \x[image-aa-zxcv-lolol-bb]. \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=aa \x[cross-reference-title-link-removal][zxcv] \a[http://example.com][lolol] bb} ]] = `\x` arguments {parent=Cross reference} = `\x` `c` argument {parent=x arguments} Capitalizes the first letter of the target title. For more details, see: {full}. = `\x` `child` argument {parent=x arguments} Setting the `child` on a cross reference to a header as in: `` \x[my-header]{child} `` makes that header show up on the list of extra parents of the child. This allows a section to have multiple parents, e.g. to include it into multiple categories. For example: `` = Animal == Mammal === Bat === Cat == Flying animal These animals fly: * \x[bat]{child} These animals don't fly: * \x[cat] `` would render something like: `` = Animal == Mammal === Bat (Parent section: Mammal) (Tags: Flying animal) === Cat (Parent section: Mammal) == Flying animal (Parent section: Animal) These animals fly: * \x[bat] These animals don't fly: * \x[cat] `` so note how "Bat" has a list of tags including "Flying animal", but Cat does not, due to the `child`. This property does not affect how the

is rendered. We could insert elements sections there multiple times, but it has the downside that browser Ctrl + F searches would hit the same thing multiple times on the table of contents, which might make finding things harder. `` == My title{id=my-id} Read this \x[my-id][amazing section]. `` If the second argument, the <`content` argument>, is not present, it expand to the header title, e.g.: `` == My title{id=my-id} Read this \x[my-id]. `` is the same as: `` == My title{id=my-id} Read this \x[my-id][My title]. `` A live demo can be seen at: <\x child argument demo>. Generally, a better alternative to this argument is to use <\H child argument>. = Secondary children {parent=x child argument} The term refers to sections that have a parent/child relationship via either of the: * <\x child argument> * <\x parent argument> * <\H child argument> rather than via the usual
hierarchy. Secondary children show up for example on the metadata section, but not on the
, which is what the header hierarchy already shows. Secondary children are normally basically used as "tags": a header such as `Bat` can be a direct child of `Mammal`, and a secondary child of `Flying animal`, or vice versa. Both `Mammal` and `Flying animal` are then basically ancestors. But we have to chose one main ancestor as "the parent", and other secondary ancestors will be seen as tags. This option first does conversion on the argument, so you can e.g. keep any spaces or use capitalization in the title as in: `` = Animal == Flying animal {child=Big bat} == Big bat `` TODO the fact that this transformation is done currently makes it impossible to use "non-standard IDs" that contain spaces or uppercase letters. If someone ever wants that, we could maybe add a separate argument that does not do the expansion e.g.: `` = Animal == Flying animal {childId=Big bat} == Big bat {id=Big bat} `` but definitely the most important use case is having easier to type and read source with the standard IDs. = `\x` `child` argument demo {parent=x child argument} {scope} = Animal {parent=x child argument demo} = Ant {parent=Animal} = Cow {parent=Animal} Oh, and cows are also {parent}. = Mammal {parent=Animal} = Bat {parent=Mammal} = Cat {parent=Mammal} = Flying animal {parent=Animal} {child} can fly. But can't. = `\x` `file` argument {parent=x arguments} Allows to link to with the <`\H` `file` argument>, e.g.: `` = My header Check out this amazing file: {file} == path/to/myfile.txt `` Some live demos follow: \OurBigBookExample[[ \x[file_demo]{file} ]] \OurBigBookExample[[ \x[file_demo/file_demo_subdir]{file} ]] \OurBigBookExample[[ \x[file_demo/file_demo_subdir/hello_world.js]{file} ]] \OurBigBookExample[[ \x[file_demo/my.bin]{file} ]] \OurBigBookExample[[ \x[Tank_man_standing_in_front_of_some_tanks.jpg]{file} ]] \OurBigBookExample[[ \x[https://www.youtube.com/watch?v=YeFzeNAHEhU]{file} ]] = `\x` `full` argument {parent=x arguments} To also show the section auto-generated number as in "Section X.Y My title" we add the optional `{full}` to the cross reference, for example: \OurBigBookExample[[\x[x-full-argument]{full}.]] `{full}` is not needed for cross references to most macros besides , which use `full` by default as seen by the `default_x_style_full` macro property in <--help-macros>. This is for example the case for . You can force this to be disabled with `{full=0}`: \OurBigBookExample[[Compare \x[image-my-test-image]{full=0} vs \x[image-my-test-image]{full=1}.]] = `\x` `full` argument in cross file references {parent=x full argument} For example in the following : \OurBigBookExample[[\x[h2-in-not-the-readme]{full}.]] we get just something like: `` Section "h2 in not the readme" `` instead of: `` Section 1.2 "h2 in not the readme" `` This is because the number "Section 1.2" might already have been used in the current page, leading to confusion. = `\x` `magic` argument {parent=x arguments} {tag=Boolean argument} = Magic link {synonym} This argument makes writing many internal links more convenient, and it was notably introduced because it serves as the sane version of . If given e.g. as in: `` = Internal reference \x[Internal references]{magic} `` the link treated magically as follows: * content capitalization and pluralization are detected from the string, and implicitly set the <\x c argument> and <\x p argument>. In the example: * `{c}` capitalization is set because `Internal references` starts with an upper case character `I` * `{p}` pluralization is set because `Internal references` ends in a plural word In this simple example, the content therefore will be exactly `Internal references` as in the source. But note that this does not necessarily need to be the case, e.g. if we had done: `` \x[Internal Reference]{magic} `` then the content would be: `` Internal reference `` without capital `R`, i.e. everything except capitalization and pluralization is ignored. This forgiving way of doing things means that writers don't need to remember the exact ideal capitalization of everything, which is very hard to remember. It also means that any more complex elements will be automatically rendered as usual, e.g. if we had: `` = \i[Internal] reference \x[internal reference]{magic} `` then the output would still contain the `` italic tag. If we had a scope as in `\x[my scope/Internal references]`, then each scope part is checked separately. E.g. in this case we would have upper case `Internal references`, even though `my scope` is lowercase, and so `{c}` would be set. * the ID is calculated as follows: * conversion is performed, with you exception: forwards slashs `/` are kept, in order to make work. In our case, there aren't any slashes `/`, so it just gives `internal-references`. But if instead we had e.g.: `\x[my scope/internal reference]{magic}`, then we would reach `my-scope/internal-reference` and not `my-scope-internal-reference`. * if there is a match to an existing ID use it. `internal-references` in the plural does not match, so go to the next step * if the above failed, try singularizing the last word as in the <\x p argument> with `p=0` before doing conversion. This gives `internal-reference`, which does exist, and so we use that. There may be some cases where you might still want to use however, see: {full}. = Insane magic link {parent=`\x` `magic` argument} {tag=Insane macro shortcut} A can be created more succinctly by surrounding the link with "angle brackets" (`<>`), e.g.: `` `` is equivalent to: `` \x[Partial derivative]{magic} `` = `\x` `parent` argument {parent=x arguments} The `parent` argument is exactly like the <\x child argument>, but it reverses the direction of the parent/child relation. = `\x` `ref` argument {parent=x arguments} The `ref` argument of `\x` marks the link as reference, e.g.: `` Trump said this and that.\x[donald-trump-access-hollywood-tape]{ref} = Donald Trump Access Hollywood tape `` renders something like: `` Trump said this and that.* `` This could currently be replicated without `ref` by just using: `` Trump said this and that.\x[donald-trump-access-hollywood-tape][*] `` but later on we might add more precise reference fields like the page of a book or date fetched as Wikipedia supports. Implemented at: https://github.com/ourbigbook/ourbigbook/issues/137 = `\x` `topic` argument {parent=x arguments} {title2=`<#Black holes>`} {tag=Boolean argument} = Topic link {synonym} {title2} If true, then the target of a this link is called a "topic link" and gets treated specially, pointing to an external rather than a header defined in the current project. For example, when rendering a , a link such as: `` \x[Albert Einstein]{topic} `` would produce output similar to: `` \a[https://ourbigbook.com/go/topic/john-smith][John Smith] `` e.g.: \OurBigBookExample[[ \x[Albert Einstein]{topic} ]] This allows static website creators to easily link to topics they might not have already written about which others may have covered. The instance linked to can be configured with . Those links also work on rendering of course, and point to the current Web instance. = Insane topic link {parent=`\x` `topic` argument} {tag=Insane macro shortcut} {title2=`<#Albert Einstein>`} If an starts with a hash sign (`#`), then it is converted to a instead of a . For example: \OurBigBookExample[[ <#Albert Einstein> ]] is equivalent to: `` \x[Albert Einstein]{topic} `` = Insane topic link with a single word {parent=Insane topic link} {tag=Insane macro shortcut} {title2=`#star`} = Insane topic links with a single word {synonym} If an is made up of a single word then it can be written in the following even succincter notation, without the need for angle brackets: \OurBigBookExample[[ I like #dogs ]] is equivalent to: `` I like <#dogs> `` Word separation is defined analogously to , i.e.: * `#` can start from anywhere, including the middle of words, e.g.: \OurBigBookExample[[ abc#mytopic ]] would produce a link immediately preceded by the characters `abc`. * `#` ends at any , e.g.: * Topic is `mytopic`: \OurBigBookExample[[ #mytopic is cool ]] * Topic is `mytopic,` with the comma: \OurBigBookExample[[ #mytopic, is cool ]] So you likely would have had instead used the sane syntax in this case with `<#mytopic>, is cool` to avoid that. = Topic link pluralization {parent=`\x` `topic` argument} Unlike local links, it is not possible to automatically determine the exact pluralization of a because: * it would require communicating with the API, which we could in principle do, but we would rather not have static builds depend on Web instances * topics can be written by multiple authors, and there could be both plural and singular versions of each topic ID, which makes it hard to determine which one is "correct" Therefore, it is up to authors to specifically specify the desired pluralization of their topic links: * by default, topic IDs are automatically singularized, e.g.: `` <#Many Dogs> `` renders something like: `` \a[https://ourbigbook.com/go/topic/many-dog][Many Dogs] `` * to prevent this automatic singularization, use <`\x` `p` argument> with `{p=1}`, e.g.: `` <#Many Dogs>{p=1} `` renders something like: `` \a[https://ourbigbook.com/go/topic/many-dogs][Many Dogs] `` = `\x` `p` argument {parent=x arguments} Pluralizes or singularizes the last word of the target title. For more details, see: {full}. = OurBigBook Markup syntax {c} {parent=OurBigBook Markup} = Insane macro shortcut {parent=OurBigBook Markup syntax} = Insane syntax {synonym} = Insane {synonym} = Insanity {synonym} Certain commonly used macros have insane macro shortcuts that do not start with backslash (`\`). Originally, [Ciro wanted to avoid those], but they just feel too good to avoid. Every insane syntax does however have an equivalent sane syntax. The style recommendation is: use the insane version which is shorter, unless you have a specific reason to use the sane version. Insane in our context does not mean worse. It just mean "harder for the computer to understand". But it is more important that humans can understand in the first place! It is find to make the computer work a bit more for us when we are able to. = Macros with insane shortcut {parent=Insane macro shortcut} * {child}{full}: `\n\n` (double newline) * {child}{full}: `a http://example.com b` (space followed by `http://`) * {child}{full}: `` (angle brackets), see: {full} * {child}{full}: `$`, described at: * {child}{full}: \c[[`]], described at: * {child}{full}: `* ` and indentation *
{child}{full}: `|| `, `| ` and indentation = Insane code and math shortcuts {parent=Macros with insane shortcut} The insane code and math shortcuts work very analogously and are therefore described together in this section. The insane inline code syntax: \OurBigBookExample[[a `b c` d]] and is equivalent to the sane: `` a \c[[b c]] d `` The insane block code: \OurBigBookExample[[ a `` b c `` d ]] and is equivalent to the sane: `` a \C[[ b c ]] d `` = Insane macro shortcut extra arguments {parent=Macros with insane shortcut} Insane arguments always work by abbreviating: * the macro name * one or more of its positional arguments, which are fixed as either [literal or non-literal] for a given insane construct This means that you can add further arguments as usual. For example, an insane code block with an id can be written as: `` a `b c`{id=ef} g `` because that is the same as: \OurBigBookExample[[a \c[b c]{id=ef} g]] So we see that the `b c` argument is the very first argument of `\c`. Extra arguments must come after the insane opening, e.g. the following does not work: `` a {id=ef}`b c` g `` This restriction things easy to parse for humans and machines alike. = Escapes in insane macro shortcuts {parent=Macros with insane shortcut} Literal backticks and dollar signs can be produced witha backslash escape as in: \OurBigBookExample[[a \` \$ b]] It is not possible to escape backticks (\c[[`]]) inside an insane inline code, or dollar signs (`$`) in insane math. The design reason for that is because multiple backticks produce block code. The upside is that then you don't have to escape anything else, e.g. backslashes (`\`) are rendered literally. The only way to do it is to use the sane syntax instead: \OurBigBookExample[[[ a \c[[b ` c]] d a \m[[\sqrt{\$4}]] d ]]] Within block code and math, you can just add more separators: \OurBigBookExample[[ ``` code with two backticks `` nice ``` ]] = Macro identifier {parent=OurBigBook Markup syntax} macro identifiers can consist of the following letters: * `a-z` lowercase * `A-Z` uppercase * `0-9` Since underscores `_` or hyphens `=` are not allowed, https://en.wikipedia.org/wiki/Camel_case[camel case] macro names are recommended, e.g. for <\OurBigBookExample> we use the name: `` OurBigBookExample `` = Macro argument {parent=OurBigBook Markup syntax} = Macro argument syntax {synonym} = Positional vs named arguments {parent=Macro argument} {title2=`[...]` vs `{key=...}`} Every argument in OurBigBook is either positional or named. For example, in a
definition with an ID: `` = My asdf {id=asdf qwer} {scope} `` which is equivalent to the [sane] version: `` \H[1][My asdf] {id=asdf qwer} {scope} `` we have: * two positional argument: `[1]` and `[My asdf]`. Those are surrounded by square brackets `[]` and have no name * two named arguments: `{id=asdf qwer}` and `{scope}`. The first one has name `id`, followed by the separator `=`, followed by the value `asdf qwer`. The separator `=` always is optional. If not given, it is equivalent to an empty value, e.g.: `` {id=} `` is the same as: `` {id} `` You can determine if a macro is positional or named by using <--help-macros>. Its output contains something like: `` "h": { "name": "h", "positional_args": [ { "name": "level" }, { "name": "content" } ], "named_args": { "id": { "name": "id" } "scope": { "name": "scope" } }, `` and so we see that `level` and the <`content` argument> are positional arguments, and `id` and `scope` are named arguments. Generally, positional arguments are few (otherwise it would be hard to know which is which is which), and are almost always used for a given element so that they save us from typing the name too many times. The order of positional arguments must of course be fixed, but named arguments can go anywhere. We can even mix positional and named arguments however we want, although this is not advised for clarity. The following are therefore all equivalent: `` \H[1][My asdf]{id=asdf qwer}{scope} \H[1][My asdf]{scope}{id=asdf qwer} \H{id=asdf qwer}{scope}[1][My asdf] \H{scope}[1]{id=asdf qwer}[My asdf] `` Just like named arguments, positional arguments are never mandatory. = Positional argument {parent=Positional vs named arguments} See: {full}. = Positional argument default values {parent=Positional argument} Most positional arguments will default to an empty string if not given. However, some positional arguments can have special effects if not given. For example, an anchor with the first positional argument present (the URL), but not the second positional argument (the link text) as in: \OurBigBookExample[[\a[http://example.com\]]] has the special effect of generating automatic links as in: `` \a[http://example.com][http://example.com] `` This can be contrasted with named arguments, for which there is always a default value, notably for . See also: {full}. = Mandatory positional arguments {parent=Positional argument} Some positional arguments are required, and if not given OurBigBook reports an error and does not render the node. This is for example the `level` of a
. These arguments marked with the `mandatory: true` <--help-macros> argument property. = Named argument {parent=Positional vs named arguments} See: {full}. = Boolean argument {child=H child argument} {child=H numbered argument} {child=H splitDefault argument} {child=x c argument} {child=x p argument} {child=x ref argument} {parent=Macro argument} Name arguments marked in <--help-macros> as `boolean: true` must either: * take no value and no `=` sign, in which case the value is implicitly set to `1` * take value exactly `0` or `1` * not be given, in which case a custom per-macro default is used. That value is the `default` from <--help-macros>, or `0` if such default is not given For example, the <\x full argument> of is correctly written as: \OurBigBookExample[[\x[boolean-argument]{full}]] without the `=` sign, or equivalently: \OurBigBookExample[[\x[boolean-argument]{full=1}]] The `full=0` version is useful in the case of reference targets that unlike expand the title on the cross reference by default, e.g. : \OurBigBookExample[[\x[boolean-argument]{full=1}]] The name "boolean argument" is given by analogy to the https://stackoverflow.com/questions/16109358/what-is-the-correct-readonly-attribute-syntax-for-input-text-elements/24588427#24588427["boolean attribute" concept in HTML5]. = Common argument {c} {parent=Macro argument} are argument names that are present in all macros. = `id` argument {parent=Common argument} Explicitly sets the ID of a macro. In , every single macro has an ID, which can be either: * explicit: extracted from some input given by the user, either the <`id` argument> or the <`title` argument>. Explicit IDs can be referenced in and must be unique * implicit: automatically generated numerical ID. Implicit IDs cannot be referenced in and don't need to be unique. Their primary application is generating on hover links next to everything you hover, e.g. arbitrary paragraphs. The most common way to assign an ID is implicitly with conversion for macros that have a <`title` argument>. The <`id` argument> allows to either override the , or provide an explicit ID for elements that don't have a <`title` argument>. = `disambiguate` argument {parent=Common argument} = `\H` `disambiguate` argument {synonym} Sometimes the short version of a name is ambiguous, and you need to add some extra text to make both its title and ID unique. For example, the word "Python" could either refer to: * the programming language: https://en.wikipedia.org/wiki/Python_(programming_language) * the genus of snakes: https://en.wikipedia.org/wiki/Python_(genus) The `disambiguate` helps you deal more neatly with such problems. Have a look at this example: \OurBigBookExample[[ My favorite snakes are \x[python-genus]{p}! My favorite programming language is \x[python-programming-language]! \x[python-genus]{full} \x[python-programming-language]{full} = Python {disambiguate=genus} {parent=disambiguate-argument} = Python {c} {disambiguate=programming language} {parent=disambiguate-argument} {title2=.py} {wiki} ]] from which we observe how `disambiguate`: * gets added to the ID after conversion following the same rules as * shows up on the header between parenthesis, much like Wikipedia, as well as in <\x full argument>[`full` cross references] * does not show up on non-`full` references. This makes it much more likely that you will be able to reuse the title automatically on a cross reference without the <`content` argument>: we wouldn't want to say "My favorite programming language is Python (programming language)" all the time, would we? * gets added to the default <\H wiki argument> inside parenthesis, following Wikipedia convention, therefore increasing the likelihood that you will be able to go with the default Wikipedia value Besides disambiguating headers, the `disambiguate` argument has a second related application: disambiguating IDs of images. For example: \OurBigBookExample[[ \x[image-the-title-of-my-disambiguate-image]{full=0} \x[image-the-title-of-my-disambiguate-image-2]{full=0} \x[image-the-title-of-my-disambiguate-image]{full} \x[image-the-title-of-my-disambiguate-image-2]{full} \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=The title of my disambiguate image} \Image[Tank_man_standing_in_front_of_some_tanks.jpg] {title=The title of my disambiguate image} {disambiguate=2} ]] Note that unlike for headers, `disambiguate` does not appear on the title of images at all. It serves only to create an unique ID that can be later referred to. Headers are actually the only case where `disambiguate` shows up on the visible rendered output. We intend on making this application obsolete however with: This use case is even more useful when `title-from-src` is enable by default for the entry, so you don't have to repeat titles several times over and over. = JavaScript interface for arguments {c} {parent=Macro argument} The JavaScript interface sees arguments as follows: `` function macro_name(args) `` where args is a dict such that: * optional arguments have the key/value pairs explicitly given on the call * mandatory arguments have a key documented by the API, and the value on the call. For example, the link API names its arguments `href` and `text`. = Literal arguments {parent=Macro argument} {title2=`[[...]]` and `{{key=...}}`} = Literal argument {synonym} Arguments that are opened with more than one square brackets `[` or curly braces `{` are literal arguments. In literal arguments, OurBigBook is not parsed, and the entire argument is considered as text until a corresponding close with the same number of characters. Therefore, you cannot have nested content, but it makes it extremely convenient to write or . For example, a multiline code block with double open and double close square brackets inside can be enclosed in triple square brackets: \OurBigBookExample[[[ A literal argument looks like this in OurBigBook: \C[[ \C[ A multiline code block. ] ]] And another paragraph. ]]] The same works for inline code: \OurBigBookExample[[[The program \c[[puts("]");]] is very complex.]]] Within literal blocks, only one thing can be escaped with backslashes are: * leading open square bracket `[` * trailing close square bracket `]` The rule is that: * if the first character of a literal argument is a sequence of backslashes (`\`), and it is followed by another argument open character (e.g. `[`, remove the first `\` and treat the other characters as regular text * if the last character of a literal argument is a `\`, ignore it and treat the following closing character (e.g. `]`) as regular text See the following open input/output pairs: `` \c[[\ b]] \ b \c[[\a b]] \a b \c[[\[ b]] [ b \c[[\\[ b]] \[ b \c[[\\\[ b]] \\[ b `` and close examples: `` \c[[a \]] a \ \c[[a \]]] a ] \c[[a \\]]] a \] `` = Argument leading and trailing newline removal {parent=Macro argument} = Argument leading newline removal {synonym} If the very first or very last character of an argument is a newline, then that character is ignored if it would be part of a regular plaintext node. For example: `` \C[[ a b ]] `` generates something like: ``
a

b
`` instead of: ``

a

b
`` This is extremely convenient to improve the readability of code blocks and similar constructs. The newline is however considered if it would be part of some . For example, we can start an [insane list] inside a as in: \OurBigBookExample[[ \Q[ * a * b ] ]] where the insane list requires a leading newline `\n* ` to work. That newline is not ignored, even though it comes immediately after the `\Q[` opening. = Argument newlines between arguments removal {parent=Macro argument} The macro name and the first argument, and any two consecutive arguments, can be optionally separated by exactly one newline character, e.g.: `` \H [2] {scope} [Design goals] `` is equivalent to: `` \H[2]{scope}[Design goals] `` which is also equivalent to: `` \H[2]{scope} [Design goals] `` This allows to greatly improve the readability of long argument lists by having them one per line. There is one exception to this however: inside an
[insane header], any newline is interpreted as the end of the insane header. This is why the following works as expected: `` == My header 2 `some code` {id=asdf} `` and the `id` gets assigned to the header rather than the trailing code element. = Document trailing newline removal {parent=Macro argument} If the document ends one newline, it is ignored. If it is two or more, then that generates an error. = Escape characters {parent=Macro argument} Every character that cannot be a can be escaped with a backslash `\`. If you try to escape a macro identifier it of course treats the thing as a macro instead and fails, e.g. in `\a` it would try to use a macro called `\a`, not escape the character `a`. For some characters, escaping or not does not make any difference because they don't have any meaning to , e.g. currently `%` is always the exact same as `\%`. But in [non-literal macro arguments], you have to use a backslash to escape the following if you want them to not have any magical meaning: * `\`: backslashes start macros * `\[` and `\]`: open and close [positional macro arguments] * `\{` and `\}`: open and close [optional macro arguments] * escapes for : * `<` (open angle brackets, less than sign): for * `$` (dollar sign): for * \c[[`]] (backtick): for * `#` (hash): Furthermore, only at: * at the start of the document * after a newline * at the start of a new argument you must also escape the following : * `* ` for insane * `| ` and `|| ` for insane * `= ` for insane The escape rules for literal arguments are described at: {full}. This is good for short arguments of regular text, but for longer blocks like or , you may want to use = Macro argument property {parent=Macro argument} Each can have certain properties associated to it. These properties have programmatic effects, and allow users and developers to more easily understand and create new macro arguments. = `remove_whitespace_children` {parent=Macro argument property} In HTML, certain elements such as `
    ` cannot have any `text` nodes in them, and any whitespace is ignored, see https://stackoverflow.com/questions/2161337/can-we-use-any-other-tag-inside-ul-along-with-li/60885802#60885802[]. A similar concept applies to OurBigBook, e.g.: `` \Ul[ \L[aa] \L[bb] ] `` does not parse as: `` \Ul[\L[aa]\L[bb]] `` but rather as: `` \Ul[\L[aa]\L[bb]] `` because the <`content` argument> of `ul` is marked with `remove_whitespace_children` and automatically removes any whitespace children (such as a newline) as a result. This also applies to consecutive sequences of macros, e.g.: `` \L[aa] \L[bb] `` also does not include the newline between the list items. The definition of whitespace is the same as the ASCII whitespace definition of HTML5: ` \r\n\f\t`. = `multiple` argument {child=H child argument} {parent=Macro argument property} By default, arguments can be given only once. However, arguments with the `multiple` property set to `true` can be given multiple times, and each time the argument is given, the new value is appended to a list containing all the values. An example is the <\H child argument>{child}. [Internally], multiple is implemented by creating a new level in the , and storing each argument separately under a newly generated dummy nodes as in: `` AstNode: H AstArgument: child AstNode: Comment AstArgument: content AstNode: plaintext AstNode: x AstNode: Comment AstArgument: content AstNode: plaintext AstNode: x `` = Pseudo-macro argument property {parent=Macro argument} This section documents ways to classify macro arguments that are analogous to , but which don't yet have clear and uniform programmatic effects and so are a bit more hand wavy for now. = `content` argument {c} {parent=Pseudo-macro argument property} The <`content` argument> of macros contains the "main content" of the macro, i.e. the textual content that will show the most proeminently once the macro is rendered. It is usually, but not always, the first of macros. We should probably make it into an official at some point. In most cases, it is quite obvious which argument is the <`content` argument>, e.g.: * <`\i` macro>: in `\i[asdf qwer]` then `asdf qwer` is the <`content` argument> * <`\a` macro>: in `\a[https://example.com][example website]` then `example website` is the <`content` argument> Some macros however don't have a <`content` argument>, especially when they don't show any textual acontent as their primary rendered output, e.g.: * <`\Image` macro>: this macro has `title` byt not content, e.g. as in: `\Image[flower.jpg]{title=}`, since the primary content is the `Image` rather than any specific text Philosophically, the <`content` argument> of a macro is analogous to the `innerHTML` of an HTML tag, as opposed to attributes such as `href=` and so on. The difference is that in , every macro argument can contain child elements, while in HTML only the `innerHTML`, but not the attributes, can. = `title` argument {c} {parent=Pseudo-macro argument property} The <`title` argument> is an argument that gets used in calculation of macro IDs. The <`title` argument> currently appears as both and Examples: * : `= My header` is equivalent to `\H[1][My header]`, and `My header` is the <`title` argument>, which is a in this case * : in `\Image[flower.jpg]{title=My header}` and `My header` is the <`title` argument>, which is a in this case = `description` argument {c} {parent=Pseudo-macro argument property} The <`description` argument> is similar to the <`title` argument> in that it adds information about some block such as an or . The difference from the title is that it does not count toward calculations. = OurBigBook Markup concepts {parent=OurBigBook Markup} These are shared concepts that are used across other sections. = `auto_parent` macro property {id=auto-parent} {parent=OurBigBook Markup concepts} Some sequences of macros such as `l` from and `tr` from automatically generate implicit parents, e.g.: `` \Ul[ \L[aa] \L[bb] ] `` parses exactly like: `` \L[aa] \L[bb] `` The children are always added as arguments of the <`content` argument> of the implicit parent. If present, the `auto_parent` macro property determines which auto-parent gets added to those macros. = Block vs inline macros {parent=OurBigBook Markup concepts} Every OurBigBook macro is either block or inline: * a block macro is one that takes up the entire line when rendered All block macros start with a capital letter, e.g. `\H` for . * and an inline macro is one that goes inside of a line. Every inline macro starts with a lowercase letter e.g. `\a` for . Some macros have both a block and an inline version, and like any other macro, those are differentiated by capitalization: * * * = Known URL protocols {parent=OurBigBook Markup concepts} Certain common URL protocols are treated as "known" by OurBigBook, and when found they have special effects in some parts of the conversion. The currently known protocols are: * `http://` * `https://` Effects of known protocols include: * : mark the start of insane links * : mark an image `src` to ignore `provider` = JavaScript case conversion {c} {parent=OurBigBook Markup concepts} Some parts of OurBigBook use "JavaScript case conversion". This means that the conversion is done as if by the `toLowerCase`/`toUpperCase` functions. The most important fact about those functions is that they do convert non-ASCII Unicode capitalization, e.g. between `É` and `é`: * https://stackoverflow.com/questions/3590833/does-javascript-string-tolowercase-follow-unicode-standards-in-case-conversion * https://stackoverflow.com/questions/929079/unicode-lowercase-characters These conversions are also specified in the Unicode standard. = JavaScript regular expression {c} {parent=OurBigBook Markup concepts} https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions = Git tracked project {c} {parent=OurBigBook Markup concepts} If the of an OurBigBook project is also a git repository, and if `git` is installed, then the OurBigBook project is said to be a "Git tracked project". = Element ID {c} {parent=OurBigBook Markup concepts} In general usages of a produces an element, and every element has an ID. IDs must be unique, and they are used as the target of . E.g. due to {full}, the elements: `` = Animal == Big dog I like . `` would have IDs respectively: * `animal` * `big-dog` Such IDs are almost always rendered as HTML IDs as something like: ``

    `` and can therefore be linked to in a page with the corresponding fragment: `` animal.html#big-dog `` = Reserved IDs {parent=element-id} = Reserved ID {synonym} IDs that start with an underscore `_` are reserved for OurBigBook usage, and will give an error if you try to use them, in order to prevent ID conflicts. For example: * the

uses an ID `_toc` the [ID] of the ToC is always fixed to `toc`. If you try to use that for another element, you will get the following error: * elements without an explicit ID may receive automatically generated IDs of type `_1`, `_2` and so on If you use a reserved ID, you will get an error mesasge of type: `` error: tmp.bigb:3:1: IDs that start with "_" are reserved: "_toc" `` = OurBigBook CLI {c} {parent=OurBigBook} = `ourbigbook` executable {synonym} {title2} OurBigBook CLI is the executable program called `ourbigbook` which comes when you install `npm install ourbigbook`. It is the main command line utility of the . Its functionality will also be exposed on GUI such as to make things nicer for non-technical users. The main functionalities of the executable are to: * convert files to HTML files or other formats The HTML files can then be either viewd from your filesystem on a browser, or uploaded and hosted very cheaply or for free so that others can see it, e.g. on . * , either to or as a Or if you are a programmer: OurBigBook CLI is a Static Wiki generator that can be invoked from the command line with the . OurBigBook CLI is how https://cirosantilli.com[] is published. OurBigBook Web takes as input the exact same format of OurBigBook Markup files used by OurBigBook CLI. TODO support/improve import/export to/from OurBigBook Web, see also: <--web>. The OurBigBook CLI calls the to convert each input file. Convert a `.bigb` file to HTML and output the HTML to a file with the same basename without extension, e.g.: `` ourbigbook hello.bigb firefox out/html/hello.html `` Files named `README.bigb` are automatically converted to `index.html` so that they will show on both GitHub READMEs and at the website's base address: `` ourbigbook README.bigb firefox out/html/index.html `` Convert all `.bigb` files in a directory to HTML files, e.g. `somefile.bigb` to `out/html/somefile.html`: `` ourbigbook . `` The HTML output files are placed right next to each corresponding `.bigb`. The output file can be selected explicitly with: . Output to stdout instead of saving it to a file: `` ourbigbook --stdout README.bigb `` In order to resolve , this actually does two passes: * first an pass, which parses all inputs and dumps their IDs to the ID database * then a second render pass, which uses the IDs in the ID database = stdin conversion {parent=OurBigBook CLI} = stdin {synonym} Convert a `.bigb` file from stdin to HTML and output the contents of `` to stdout: `` printf 'ab\ncd\n' | ourbigbook --body-only `` Stdin converion is a bit different from conversion from a file in that it ignores the and any other setting files present in the current directory or its ancestors. Also, it does not produce any changes to the . In other words, a conversion from stdin is always treated as if it were outside of any project, and therefore should always produce the same results regardless of the current working directory. = OurBigBook CLI quick start {parent=OurBigBook CLI} = Play with the template {parent=OurBigBook CLI quick start} Learn the syntax basics in 5 minutes: https://docs.ourbigbook.com/editor[]. Play with https://github.com/ourbigbook/template[an OurBigBook template] locally: `` git clone https://github.com/ourbigbook/template cd template npm install npx ourbigbook . firefox out/html/index.html `` That template can be seen rendered live at: http://cirosantilli.com/ourbigbook-generate-multifile/ Other templates are documented at: <--generate>. To on your repository you can just fork the repository https://github.com/ourbigbook/template to your own https://github.com/johndoe/template and then: `` git remote set-url origin git@github.com:johndoe/template.git npx ourbigbook --publish `` and it should now be visible at: https://johndoe.github.io/template Then, every time you make a change you can publish the new version with: `` git add . git commit --message 'hacked stuff' ourbigbook --publish . `` or equivalently with the shortcut: `` ourbigbook --publish-commit 'hacked stuff' `` If you want to publish to your root page https://johndoe.github.io instead of https://johndoe.github.io/template you need to rename the `master` branch to `dev` as mentioned at : `` git remote set-url origin git@github.com:johndoe/johndoe.github.io.git # Rename master to dev, and delete the old master. git checkout -b dev git push origin dev:dev git branch -D master git push --delete origin master npx ourbigbook --publish `` The following files of the template control the global style of the output, and you are free to edit them: * `ourbigbook.liquid.html`: global HTML template in https://shopify.github.io/liquid/[Liquid format]. Available variables are documented at <--template>{full} * `main.scss`: https://sass-lang.com/[Sass] file that gets converted to raw CSS `main.css` by `npx ourbigbook .`. Sass is just much more convenient to write than raw CSS. That file gets included into the global HTML template inside `ourbigbook.liquid.html` at: `` `` = Important command line options {parent=OurBigBook CLI quick start} When you run: `` npx ourbigbook . `` it converts all files in the current directory separately, e.g.: * `README.bigb` to `out/html/index.html`, since `README` is a magic name that we want to show on the root URL * `not-readme.bigb` to `out/html/not-readme.html`, as this one is a regular name unlike `README` * `main.scss` to `main.css` If one of the input files starts getting too large, usually the toplevel `README.bigb` in which you dump everything by default like Ciro does, you can speed up development and just compile files individually with either: `` npx ourbigbook README.bigb npx ourbigbook not-readme.bigb `` Note however that when those individual files have a to something defined in `not-readme.bigb`, e.g. via `\x[h2-in-not-the-readme]`, then you must have first previously done pass once with: `` npx ourbigbook . `` to parse all files and extract all necessary IDs to the . That would be optimized slightly with the <--no-render> command line option: `` npx ourbigbook --no-render . `` to only extract the IDs but not render, which speeds things up considerably When dealing with large files, you might also be interested in the following amazing options: * * <\H splitDefault argument> = Produce a standalone HTML file {parent=Important command line options} To produce a single standalone output file that contains everything the viewer needs to correctly see the page do: `` npx ourbigbook --embed-resources --embed-includes README.bigb `` You can now just give the generated `out/html/index.html` to any reader and they should be able to view it offline without installing anything. The flags are: * <--embed-includes>: without this, `\Include[not-readme]` shows as a link to the file `out/html/not-readme.html` which comes from `not-readme.bigb` With the flag, `not-readme.bigb` output gets embedded into the output `out/html/index.html` directly * <--embed-resources>: by default, we link to CSS and JavaScript that lives inside `node_modules`. With this flag, that CSS and JavaScript is copied inline into the document instead. One day we will try to handle that way as well = Useless knowledge {parent=OurBigBook CLI quick start} Install the NPM package globally and use it from the command line for a quick conversion: `` npm install -g ourbigbook printf 'ab\ncd\n' | ourbigbook --body-only `` or to a file: `` printf 'ab\ncd\n' | ourbigbook > tmp.html `` You almost never want to do this except when , as it won't be clear what version of `ourbigbook` the document should be compiled with. Just be a good infant and use OurBigBook [with the template] that contains a `package.json` via `npx`, OK? Furthermore, the default install of Chromium on Ubuntu 21.04 uses Snap and blocks access to dotfiles. For example, in a sane NVM install, our global CSS would live under `/home/ciro/.nvm/versions/node/v14.17.0/lib/node_modules/ourbigbook/_obb/ourbigbook.css`, which gets blocked because of the `.nvm` part: * https://forum.snapcraft.io/t/dot-files/7062 * https://bugs.launchpad.net/snapd/+bug/1607067 * https://superuser.com/questions/1546550/chromium-81-wont-display-dotfiles-anymore * https://askubuntu.com/questions/1184357/why-cant-chromium-suddenly-access-any-partition-except-for-home * https://askubuntu.com/questions/1214346/as-a-user-is-there-any-way-to-change-the-confinement-of-a-snap-package One workaround is to use <--embed-resources>, but this of course generates larger outputs. To run master globally from source for development see: {full}. This one actually works despite the dotfile thing since your development path is normally outside of dotfiles. Try out the JavaScript API with \a[lib_hello.js]: `` npm install ourbigbook ./lib_hello.js `` = Publish your content {parent=OurBigBook CLI} = Publish {synonym} = Publishing {synonym} = Published {synonym} There are two ways to publish your content: * as a . This means that you generate HTML files from files and then publish them either by: * uploading to a static website server such as by using the <--publish> option * converting with <--publish-target `local`> and sending a zip with the pages to someone to view locally * to an instance such as . This can be done either by: * editing on the directly in your browser * uploading files from your computer with the <--web> option A fundamental design choice of the is that, except for bugs, a single source tree can be published in both of those ways without any changes. The trade-offs between the two options are highlighted at: . \Video[https://www.youtube.com/watch?v=Ghvlztiu6rI] {title=Edit locally and publish demo} {height=720} {width=720} = OurBigBook Web vs static website publishing {parent=Publish your content} * are cheaper to host, including many free options such as . This means that you are likely to always have several free or cheap choices of where to upload your content to, making it essentially all but https://en.wiktionary.org/wiki/TEOTWAWKI[TEOTWAWKI]-proof Pages will also load slightly fatser. * has killer multi-user features: , article upvotes and Furthermore, it also has some non multi-user features which cannot be feasibly implemented in a static website because they would require too much storage, on the fly generation is the only feasible way to deal with them: * * article history. Unimplemented as of writing: https://github.com/ourbigbook/ourbigbook/issues/248 Its main downside is that it is more expensive to host. The will do its best to keep uploading as free as possible, but upload limits necessarily have to be more strict than those of static websites, as the underlying operating cost is larger. = Index file {parent=OurBigBook CLI} The following basenames are considered "index files": * `README.bigb` * `index.bigb` Those basenames have the following magic properties: * the default output file name for an index file in HTML output is either: * `index.html` when in the . E.g. `README.bigb` renders to `index.html`. Note that GitHub and many other static website hosts then automatically hide the `index.html` part from the URL, so that your `README.bigb` hosted at `http://example.com` will be accessible simply under `http://example.com` and not `http://example.com/index.html` * the name of the subdirectory in which it is located when not in the . E.g. `mysubdir/index.bigb` outputs to `mysubdir.html` Previously, we had placed the output in `mysubdir/index.html`, but this is not as nice as it makes GitHub pages produce URLs with a trailing slash as `mysubdir/`, which is ugly, see also: https://stackoverflow.com/questions/5948659/when-should-i-use-a-trailing-slash-in-my-url * the default [toplevel header] ID of an index files is derived from the parent directory basename rather than from the source file basename = Project toplevel directory {parent=Index file} This directory is determined by first checking the presence of a file. If a is found, then the project toplevel directory is the directory that contains that file. * otherwise, if the input path is a descendant of the current working directory, then the current working directory is used, see also: * otherwise, if the input path is a directory, it is used * otherwise, the directory containing the input file is used For example, consider the file following file structure relative to the current working directory: `` path/to/notindex.bigb `` In this case: * if there is no `ourbigbook.json` file: * if we run `ourbigbook .`: the toplevel directory is the current directory `.`, and so `notindex.bigb` has ID `path/to/notindex` * if we run `ourbigbook path`: same * if we run `ourbigbook path/to`: same * if we run `ourbigbook path/to/notindex.bigb`: same * if there is a `path/ourbigbook.json` file: * if we run `ourbigbook .`: the toplevel directory is the current directory `.` because the `ourbigbook.json` is below the entry point and is not seen, and so `notindex.bigb` has ID `path/to/notindex` * if we run `ourbigbook path`: the toplevel directory is the directory with the `ourbigbook.json`, `path`, and so `notindex.bigb` has ID `to/notindex` * if we run `ourbigbook path/to`: same * if we run `ourbigbook path/to/notindex.bigb`: same = The toplevel index file {parent=Project toplevel directory} This is the present in the . Being the toplevel index file has the following implications compared to other : * its ID is derived from the header itself, not the directory, see also: = The index article {parent=The toplevel index file} The "index article" is the first article of the . E.g. in: README.bigb `` = John Smith's Homepage == I like dogs `` then "John Smith's Homepage" is the index article of the project, but "I like dogs" is not. = The current working directory does not matter when there is a `ourbigbook.json` {parent=The toplevel index file} When the file or directory being converted has an ancestor directory with a `ourbigbook.json` file, then your current working directory does not have any effect on OurBigBook output. For example if we have: `` /project/ourbigbook.json /project/README.bigb /project/subdir/README.bigb `` then all of the following conversions produce the same output: * directory conversion: * `cd /project && ourbigbook .` * `cd / && ourbigbook project` * `cd project/subdir && ourbigbook ..` * file conversion: * `cd /project && ourbigbook README.bigb` * `cd / && ourbigbook project/README.bigb` * `cd project/subdir && ourbigbook ../README.bigb` When there isn't a `ourbigbook.json`, everything happens as though there were an empty `ourbigbook.json` file in the current working directory. So for example: * outputs that would be placed relative to inputs are still placed in that place, e.g. `README.bigb -> index.html` always stay together * outputs that would be placed next to the `ourbigbook.json` are put in the current working directory, e.g. Internally, the general philosophy is that the JavaScript API in \a[index.js] works exclusively with paths relative to the . It is then up to callers such as \a[ourbigbook] to ensure that filesystem specifics handle the relative paths correctly. = OurBigBook CLI options {c} {parent=OurBigBook CLI} = `ourbigbook` executable options {synonym} = `--check-db-only` {parent=OurBigBook CLI options} Check the database for consistency, e.g. duplicated IDs. Don't do anything else, including , which must have been done previously. The initial use case was for usage in . = `--china` {parent=OurBigBook CLI options} This is the most important option of the software. It produces a copy of the HTML of https://cirosantilli.com/china-dictatorship to stdout. The data is stored inside an NPM package, making it hard to censor that information, see also: https://cirosantilli.com/china-dictatorship#mirrors Usage: `` ourbigbook --china > china.html firefox china.html `` = `--dry-run` {parent=OurBigBook CLI options} The `--dry-run` option is a good way to debug the <--publish option>, as it builds the publish output files without doing any git commands that would be annoying to revert. So after doing: `` ourbigbook --dry-run --publish . `` you can just go and inspect the generated HTML to see what would get pushed at: `` cd out/publish/out/publish/ `` see also: . Inspiration: https://github.com/cirosantilli/linux-kernel-module-cheat/tree/6d0a900f4c3c15e65d850f9d29d63315a6f976bf#dry-run-to-get-commands-for-your-project = `--dry-run-push` {parent=--dry-run} Similar to <--dry-run>, but it runs all git commands except for `git push`, which gives a clearer idea of what `--publish` would actually do including the git operations, but without publishing anything: `` ./ourbigbook --dry-run --publish . `` = `--embed-includes` {parent=OurBigBook CLI options} Makes render the included content in the same output file as the include is located, instead of the default behaviour of creating links. For example given: README.bigb `` = Index \Include[notindex] `` notindex.bigb `` = Notindex A paragraph in notindex. == Notindex 2 `` then for conversion with: `` ourbigbook --embed-includes README.bigb `` then the output `index.html` contains an output equivalent to if your input file were: `` = Index == Notindex A paragraph in notindex. === Notindex 2 `` Note that a prior pass is not required, `--embed-includes` just makes `\Include` read files as they are found in the source. Note that a In addition to this: * are disabled, and the cross file ID database does not get updated. It should be possible to work around this, but we are starting with the simplest implementation that forbids it. The problem those cause is that the IDs of included headers show as duplicate IDs of those in the ID database. This should be OK to start with because the more common use case with `--html-single-page` is that of including all headers in a single document. TODO: this option is gone. Otherwise, `include` only adds the headers of the other file to the table of contents of the current one, but not the body of the other file. The ToC entries then point to the headers of the included external files. You may want to use this option together with <--embed-resources> to produce fully self-contained individual HTML files for your project. = `--embed-resources` {parent=OurBigBook CLI options} Embed as many external resources such as images and CSS as possible into the HTML output files, rather than linking to external resources. For example, when converting a simple document to HTML: index.bigb `` = Index My paragraph. `` with: `` ourbigbook index.bigb `` the output contains references to where OurBigBook is installed in our local filesystem: `` `` The advantage of this is that we don't have to duplicate this for every single file. But if you are giving this file to someone else, they would likely not have those files at those exact locations, which would break the HTML page. With `--embed-resources`, the output contains instead something like: `` `` This way, all the required CSS and JavaScript will be present in the HTML file itself, and so readers will be able to view the file correctly without needing to install any missing dependencies. The use case for this option is to produce a single HTML file for an entire build that is fully self contained, and can therefore be given to consumers and viewed offline, much like a PDF. Examples of embeddings done: * CSS and JavaScript are copy pasted in place into the HTML. The default built-in CSS and JavaScript files used by OurBigBook (e.g. the KaTeX CSS [used for mathematics]) are currently all automatically downloaded as NPM package dependencies to ourbigbook Without `--embed-resources`, those CSS and JavaScript use their main cloud CDN URLs, and therefore require Internet connection to view the generated documents. The embedded version of the document can be viewed offline however. There is however a known bug: KaTeX fonts are not currently embedded, so math won't work properly. The situation is similar as for images, but a bit harder because we also need to fetch the blobs from the CSS, which is likely doable from Webpack: * https://github.com/ourbigbook/ourbigbook/issues/157 * https://stackoverflow.com/questions/41657087/webpack-inline-font-with-url-loader * https://stackoverflow.com/questions/35369419/how-to-use-images-in-css-with-webpack Examples of embedding that could be implemented in the future: * are downloaded if needed and embedded as `data:` URLs. Doing this however has a downside: it would slow the page loading down. The root problem is that HTML was not designed to contain assets, and notably it doesn't have byte position indices that can tell it to skip blobs while parsing, and how to refer to them later on when they show up on the screen. This is kind of why EPUB exists: https://github.com/ourbigbook/ourbigbook/issues/158 Images that are managed by the project itself and already locally present, such as those inside the project itself or due to usually don't require download. For images linked directly from the web, we maintain a local download cache, and skip downloads if the image is already in the cache. To re-download due to image updates, use either: * `--asset-cache-update`: download all images such that the local disk timestamp is older than the HTTP modification date with https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since[`If-Modified-Since`] * `--asset-cache-update-force`: forcefully redownload all assets Keep in mind that certain things can never be embedded, e.g.: * YouTube videos, since YouTube does not offer any download API = -`F`, `--force-render` {id=force-render} {parent=OurBigBook CLI options} Always render all selected files, irrespectively of if they are known to be outdated or not. OurBigBook stores the timestamp of the last successful step for each file. For , we always skip the extraction if the filesystem timestamp of a source file is older than the last successful extraction. For render: * we mark output files as outdated when the corresponding source file is parsed * we also skip rendering non-outdated files by default when you invoke ourbigbook on a directory, e.g. `ourbigbook .`, as this greatly speeds up the interactive error fixing turnaround time * we always re-render fully when you specify a single file, e.g. `ourbigbook path/to/README.bigb` However, note that skipping renders, unlike for ID extraction, can lead to some outdated pages. This option disables the timestamp skip for rendering, so ensure that you will get a fully clean updated render. E.g. consider if you had two files: file1.bigb `` = File 1 == File 1 1 `` file2.bigb `` = File 2 == File 2 1 \x[file-1-1] `` We then do the initial conversion: `` ourbigbook . `` we see output like: `` extract_ids file1.bigb extract_ids file1.bigb finished in 45.61287499964237 ms extract_ids file2.bigb extract_ids file2.bigb finished in 15.163879998028278 ms render file1.bigb render file1.bigb finished in 23.21016100049019 ms render file2.bigb render file2.bigb finished in 25.92908499762416 ms `` indicating full conversion without skips. But then if we just modify fil1.bigb as: `` = File 1 == File 1 1 hacked {id=file-1-1} `` the following conversion with `ourbigbook .` would look like: `` extract_ids file1.bigb extract_ids file1.bigb finished in 45.61287499964237 ms extract_ids file2.bigb extract_ids file2.bigb skipped by timestamp render file1.bigb render file1.bigb finished in 41.026930000633 ms render file2.bigb render file2.bigb skipped by timestamp `` and because we skipped `file2.bigb` render, it will still have the outdated "File 1 1" instead of "File 1 1 hacked". We could in principle solve this problem by figuring out exactly which files need to be changed when a given ID changes, and we already [have to solve a similar problem due to query bundling]. Also, this will need to be done sonner or later for the . But lazy now: https://github.com/ourbigbook/ourbigbook/issues/207[], this is hard stuff. = `--format-source` {parent=OurBigBook CLI options} Parse and overwrite the local .bigb input source files with the recommended code format. E.g.: `` ourbigbook README.bigb `` overwrites `README.bigb` with the recommended formatting, and: `` ourbigbook . `` does that for every single file in the current directory. This option uses the . In order to reach a final stable state, you might need to run the conversion twice. This is not ideal but we don't have the patience to fix it. The reason is that links in image titles may expand twice. This is the usual type of two level recursion that has caused much more serious problems, see e.g. <\x within title restrictions>. E.g. starting with: `` \Image[image.png]{title=My } = Big dog `` the first conversion leads to uppercasing inside the image title: `` \Image[image.png]{title=My } = Big Dog `` and the second one to uppercasing the reference to the image title: `` \Image[image.png]{title=My } = Big Dog `` = `--generate` {parent=OurBigBook CLI options} Generate one of the template repositories locally: * `ourbigbook --generate default`: a good starter template that illustrates many key OurBigBook features * https://github.com/ourbigbook/template * https://ourbigbook.github.io/template * `ourbigbook --generate min`: a minimal template that is still sane * https://github.com/ourbigbook/template-min * https://ourbigbook.github.io/template-min * `ourbigbook --generate subdir`: a template in which OurBigBook source is located a subdirectory `docs/`: * https://github.com/ourbigbook/template-subdir * https://ourbigbook.github.io/template-subdir This template illustrates that everything works exactly as if OurBigBook source were in the git repository toplevel. This is a convenient setup for programming projects that want to use OurBigBook for their documentation without polluting their toplevel. End users almost never want this, because it means that to have a sane setup you need to: * install OurBigBook globally with `npm install -g ourbigbook` * generate the template * then install OurBigBook locally again with `npm install` so maybe we should just get rid of that option and just ensure that we can provide an up-to-date working template for the latest relase. For now we are keeping this as it is useful to automate the updating of templates during the . = `--help-macros` {parent=OurBigBook CLI options} You can get an overview of all macros in JSON format with: `` ourbigbook --help-macros `` = `--log` {parent=OurBigBook CLI options} Give multiple times to enable a list of certain types of logs to stderr help debugging, e.g.: `` ./ourbigbook --log ast tokens -- README.bigb `` Note that this follows https://github.com/tj/commander.js/tree/e0e723810357e915210af38ccf5098ffe1fb8e65#variadic-option[commander.js' insane variadic argumentso syntax], and thus the `--` is required above. If you want to omit it for a single value you have to add the `=` sign as in: `` ./ourbigbook --log=ast README.bigb `` Values not documented in other sections: * `ast`: the full final parsed as JSON * `ast-simple`: a simplified view of the with one AstNode or AstArgument per line and showing only the most important fields * `ast-pp-simple`: view snapshots of the various post process stages, more info at: * `ast-inside`: print the AST from inside the `ourbigbook.convert` call before it returns. This is useful to debug the program if `ourbigbook.convert` blows up on the next stages before returning. * `db`: show database transactions done by OurBigBook, to help debug stuff like * `mem`: show process memory usage as per Node.js' `process.memoryUsage()` after each <--log perf> step: https://stackoverflow.com/questions/12023359/what-do-the-return-values-of-node-js-process-memoryusage-stand-for[]. Implies <--log perf>. To use this options, you must run OurBigBook with the `--expose-gc` command line option, e.g. with: `` node --expose-gc $(which ourbigbook) myfile.bigb `` * `parse`: parsing steps * `tokenize`: tokenization steps * `tokens`: final parsed token stream * `tokens-inside`: like `ast-inside` but for tokens. Also adds token index to the output, which makes debugging the parser way easier. = `--log headers` {parent=--log} This nifty little option outputs to stderr what the header graph looks like! It is a bit like a
in your terminal, for when you need to have a look at the outline of the document to decide where to place a new header, but are not in the mood to open a browser or use the . Sample output excerpt for this document: `` = h1 ourbigbook == h2 1 quick-start == h2 2 design-goals === h3 2.1 saner === h3 2.2 more-powerful == h2 3 paragraphs == h2 4 links `` This option can also serve as a debug tool for header tree related features (confession: that was its original motivation!). TODO = `--log perf` {parent=--log} print statistics to stderr, for example `` ./ourbigbook --log=perf README.bigb `` could output: `` perf start: 181.33060800284147 perf tokenize_pre: 181.4424349963665 perf tokenize_post: 318.333980999887 perf parse_start: 319.1866770014167 perf post_process_start: 353.5477180033922 perf post_process_end: 514.1527540013194 perf render_pre: 514.1708239987493 perf render_post: 562.834307000041 perf end: 564.0349840000272 perf convert_input_end 566.1234430000186 perf convert_path_pre_sqlite 566.1564619988203 perf convert_path_pre_sqlite_transaction 566.2528780028224 perf convert_path_post_sqlite_transaction 582.256645001471 perf convert_path_end 582.3469280004501 `` which shows how long different parts of the [conversion process] took to help identify bottlenecks. This option can also be useful to mark phases of the conversion to identify from which phase other logs are coming from, e.g. if we wanted to know which part of the conversion is making a ton of database requests we could run: `` ourbigbook --log db perf -- README.bigb `` and we would see the database requests made at each conversion phase. Note that `--log perf` currently does not take sub-converts into account, e.g. and <\OurBigBookExample> both call the toplevel conversion function `convert`, and therefore go through all the conversion intervals, but we do not take those it account, and just dump them all into the same toplevel interval that they happen in, currently between `post_process_start` and `post_process_end`. = `--no-check-db` {parent=OurBigBook CLI options} = `--skip-check-db` {synonym} Skip the database sanity check that is normally done after the step. This was originally added to speed up, originally added to speed up the development loop, when we knew that there were no errors in the database after a local conversion, and wanted to get to the upload phase faster, but the DB check can take several seconds for a large input. But it then later also found usage with followed by a <--check-db-only>. = `--no-db` {parent=OurBigBook CLI options} Don't use the during this run. This implies that the on-disk database is not read, and also not written to. Instead, a temporary clean in-memory database is used. = `--no-html-x-extension` {parent=OurBigBook CLI options} If not given, render with the `.html` extension as in: `` `` This way, those links will work when rendering locally to `.html` files which is the default behaviour of: `` ourbigbook . `` If given however, the links render without the `.html` as in: `` `` which is what is needed for servers such as GitHub Pages, which automatically remove the `.html` extension from paths. This option is automatically implied when [publishing to targets that remove the `.html` extension such as GitHub pages]. = `--no-render` {parent=OurBigBook CLI options} Only extract IDs to fill the , don't render. This saves time if you only want to render a single file which has references to other files without getting any errors. = `--no-web-render` {parent=OurBigBook CLI options} Same as <`--no-render`>, but for the <--web> upload stage. Web upload consists of two stages: * extract local ids and render to split ourbigbook files. This can be disabled with <--no-render> * upload to web first on an pass, and then a render pass. <`--no-web-render`> skips that render pass = `--outdir ` {id=outdir} {parent=OurBigBook CLI options} Set a custom output directory for the conversion. If not given, the is used. Suppose we have an input file `./test.bigb`. Then: `` ourbigbook --outdir my_outdir test.bigb `` places its output at: `` my_outdir/test.html `` The same would happen if we instead did a full directory conversion as in: `` ourbigbook --outdir my_outdir . `` The output would also be placed in `my_outdir/test.html`. This option also relocates to the target destination, e.g.: `` ourbigbook --outdir my_outdir test.bigb `` would generate: `` my_outdir/out `` This means that the source tree remains completely clean, and every output and temporary cache is put strictly under the selected `--outdir`. = `--outfile ` {id=outfile} {parent=OurBigBook CLI options} Save the output to a given file instead of outputting to stdout: `` ./ourbigbook --outfile not-readme.html not-readme.bigb `` The generated output is slightly different than that of: `` ./ourbigbook not-readme.bigb > not-readme.html `` because with `--outfile` we know where the output is going, and so we can generate relative includes to default CSS/JavaScript files. = `-O --output-format ` {id=output-format} {parent=OurBigBook CLI options} Default: . = `html` output format {parent=output format} The default output format. Web pages!!! = `bigb` output format {parent=output format} Outputs as , i.e. the same format as the input itself! While using `-O bigb` is not a common use case, the existence of this format has the following applications: * automatic source code formatting e.g. with <--format-source>. The recommended format, including several edge cases, can be seen in the test file \a[test_bigb_output.bigb], which should be left unchanged by a `bigb` conversion. * manipulating source code on to allow editing either individual sections separatelly, or multiple sections at once * this could be adapted to allows us to migrate updates with breaking changes to the source code more easily. Alternatively on , we might just start storing the instead of source, and just rendering the source whenever users want to edit it. Can be tested interactively with: `` ourbigbook --no-db -O bigb --stdout --log=ast-simple test_bigb_output.bigb `` One important property of the `bigb` conversion is that is must not alter the , and therefore neither the final output, in any way. One good test is: `` ourbigbook README.bigb && mv out/html/index.html out/html/old.html && ourbigbook --format-source README.bigb && ourbigbook README.bigb && diff -u out/html/old.html out/html/index.html `` This was tracked at: https://github.com/ourbigbook/ourbigbook/issues/83 = `id` output format {parent=output format} This output format is used an intermediate step in , that unlike the regular HTML output does not have any tags. It does not have serious applications to end users. We decided to expose it from the CLI mostly for fun, as it posed no extra work at all as it is treated internally exactly like any other conversion format. The <`id` output format> conversion is very simplistic: it basically just extracts the <`content` argument> of most macros. An important exception to that behaviour is the first argument of the <`\x` macro>: see <\x id output format>. For example, converting: `` \i[asdf] `` with the `id` output format produces simply: `` asdf `` instead of the HTML output: `` asdf `` This conversion type is useful in situations that users don't expect conversion to produce any HTML tags. For example, you could create a header: `` = My \i[asdf] `` and then following the algorithm, that header would have the more commonly desired ID `my-asdf`, and not `my-asdf` or `my-i-asdf-i`. Similarly, any that references an ID undergoes <`id` output format> conversion. E.g. the above header could be referenced by: `` `` which is equivalent to: `` \x[my-asdf] `` Besides being more intuitive, this conversion also guarantees greater format portability, in case we ever decide to support other output formats besides HTML! that don't have a <`content` argument> are just completely removed, i.e. typically non-textual macros such as . We could put effort in outputting their title argument correctly, but meh, not worth the effort. The <`id` output format> also serves as a good start generalizing OurBigBook to multiple outputs, as this is a simple format. = `\x` `id` output format {parent=id output format} `\x` uses `href` if the content is not given explicitly. Previously, if `\x` didn't have a content, we were actually rendering the `\x` to calculate the ID. But then we noticed that doing so would require another parse pass, so we just went for this simpler approach. This is closely linked to <\x within title restrictions>. For example in: `` = Animal \x[image-i-like-dog] \Image[dog.jpg] {title=I \i[like] \x[dog]} == Dog hacked {id=dog} `` If you wanted `image-i-like-dog-hacked` instead, you would need to explicitly give it as in: `` = Animal \x[image-i-like-dog-hacked] \Image[dog.jpg] {title=I like \x[dog][dog hacked]} == Dog hacked {id=dog} `` For similar reasons as the above, `{p}` inflection with the <\x p argument> is not considered either, e.g. you would have: `` = Animal \x[image-i-like-dog] \Image[dog.jpg] {title=I like \x[dog]{p}} == Dog `` and not: `` \x[image-i-like-dogs] `` This can however be worked around with the <\x magic argument> as in; `` = Animal \x[image-i-like-dogs] \Image[dog.jpg] {title=I like } == Dog `` = Unimplemented output formats {parent=id output format} = `latex` output format {parent=Unimplemented output formats} TODO: https://github.com/ourbigbook/ourbigbook/issues/38 One day, one day. Maybe. = `-p`, `--publish` {parent=OurBigBook CLI options} {tag=Publish your content} = `--publish` option {synonym} = Static website {synonym} = `ourbigbook --publish` {synonym} OurBigBook tooling is so amazing that we also take care of the HTML publishing for you! Once a publish target is properly setup, all you have to do is run: `` git add README.bigb git commit -m 'more content!' ourbigbook --publish `` and your changes will be published to the default target specified in . If not specified, e.g. with the the <--publish-target> option, the default target is to . Only changes committed to Git are pushed. Files that `ourbigbook` knows how to process get processed and only their outputs are added to the published repo, those file types are: * `.bigb` files are converted to `.html` * `.scss` files are converted to `.css` Every other Git-tracked file is pushed as is. When `--publish` is given, stdin input is not accepted, and so the current directory is built by default, i.e. the following two are equivalent: `` ./ourbigbook --publish ./ourbigbook --publish . `` Publishing only happens if the build has no errors. = `-P, --publish-commit ` {id=publish-commit} {parent=OurBigBook CLI options} Like the <--publish option>, but also automatically: * `git add -u` to automatically add change to any files that have been previously git tracked * `git commit -m ` to create a new commit with those changes This allows you to publish your changes live in a single command such as: `` ourbigbook --publish-commit 'my amazing change' . `` With great power comes great responsibility of course, but who cares! = `--publish-no-convert` {parent=OurBigBook CLI options} Attempt to publish without converting first. Implies the <--publish option>. This can only work if there was previously a successful publish conversion done, which later failed to publish during the following steps, e.g. due to a network error. This option was introduced for debugging purposes to help get the git commands right for large conversions that took a look time. = `--publish-target` {parent=OurBigBook CLI options} {tag=Publish your content} What type of target to publish for. The generated output of each publish target is stored under: `` out/publish/out/ `` e.g.: `` out/publish/out/local `` = `--publish-target github-pages` {parent=`--publish-target`} Publish to <#GitHub Pages>. See also: {full}. = `--publish-target local` {parent=`--publish-target`} Publish as a local directory that can be zipped and sent to someone else, and then correctly viewed by a browser locally by the receiver. You can then zip it from the Linux command line for example with: `` cd out/publish/out zip -r local.zip local `` Maybe we should do the Zip step from the as well. There is no Node.js standard library wrapper however apparently: https://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js = Publish to GitHub Pages {parent=`--publish-target`} = GitHub Pages {synonym} = Published to GitHub Pages {synonym} https://pages.github.com/[GitHub pages] is the default OurBigBook publish target. Since that procedure is so important, it is documented directly at: . = Publish to GitHub pages root page {parent=Publish to GitHub Pages} If you want to publish your root user page, which appears at `/` (e.g. https://github.com/cirosantilli/cirosantilli.github.io for the user `cirosantilli`), GitHub annoyingly forces you to use the `master` branch for the HTML output: * https://github.com/isaacs/github/issues/212 * https://stackoverflow.com/questions/31439951/how-can-i-use-a-branch-other-than-master-for-user-github-pages This means that you must place your `.bigb` input files in a branch other than `master` to clear up `master` for the generated HTML. `ourbigbook` automatically detects if your repository is a root repository or not by parsing `git remote` output, but you must setup the branches correctly yourself. So on a new repository, you must https://stackoverflow.com/questions/42871542/how-to-create-a-git-repository-with-the-default-branch-name-other-than-master[first checkout to a different branch] as in: `` git init git checkout -b dev `` or to move an existing repository to a non-master branch: `` git checkout -b dev git push origin dev:dev git branch -D master git push --delete origin master `` You then will also want to set your default repository branch to `dev` in the settings for that repository: https://help.github.com/en/github/administering-a-repository/setting-the-default-branch = `.github` directory is ignored on GitHub pages {parent=Publish to GitHub Pages} It's a GitHub bug/feature: https://github.com/orgs/community/discussions/52252 Maybe we should just ignore the `.github` directory when publishing, otherwise it leads to a broken link on the <`_dir` directory> listings. = `-S`, `--split-headers` {id=split-headers} {parent=OurBigBook CLI options} {title2=Split headers} = Split header {synonym} Split each header into its own separate HTML output file. This option allows you to keep all headers in a single source file, which is much more convenient than working with a billion separate source files, and let them grow naturally as new information is added, but still be able to get a small output page on the rendered website that contains just the content of the given header. Such split pages: * load faster on the browser * get way better Google PageRank for title hits * allow for full metadata display, e.g.: *
* https://en.wikipedia.org/wiki/Disqus[Disqus]/https://github.com/giscus/giscus[Giscus] comments For example given an input file called `hello.bigb` and containing: `` = h1 h1 content. A link to another section: \x[h1-1]. == h1 1 h1-1 content. == h1 1 1 h1-1-1 content. == h1 1 2 h1-1-2 content. `` a conversion command: `` ourbigbook --split-headers hello.bigb `` would produce the following output files: * `hello.html`: contains the entire rendered document as usual. Remember that this is called `hello.html` instead of `h1.html` because [the toplevel header ID is automatically derived from its filename]. Each header contains a on-hover link to the single-file split version of the header. * `hello-split.html`: contains only the contents directly under `= h1`, but not under any of the subheaders, e.g.: * `h1 content.` appears in this rendered output * `h1-1-1` does not appear in this rendered output The `-split` suffix can be customized with the <\H splitSuffix argument> option. The `-split` suffix is appended in order to differentiate the output path from `hello.html` * `h1-1.html`, `h1-1-1.html`, `h1-1-2.html`: contain only the contents direcly under their headers, analogously to `hello-split.html`, but now we don't need to worry about the input filename and collisiont, and just directly use the ID of each header `--split-headers` is implied by the <--publish option>: the published website will automatically get the split pages. There is no way to turn it off currently. A pull request would be accepted, especially if it offers a way to do it. Maybe it would be nice to have a more generalized way of setting any CLI option equivalent from the `ourbigbook.json`, and an option `cli` vs `cli-publish` so that `cli-publish` is publish only. Just lazy for now/not enough pressing use case met. = Cross reference targets in split headers {parent=split headers} By default, all cross references point to the non-split version of headers, including those found in split headers. The rationale for this is that it gives readers the most context around the header by simply scrolling. For example, considering the example document at , such as `\x[h1-1]` would point: * from the non-split `hello.html` to the section in the current non-split file `#h1-1` * from split `hello-split.html` to the same section in non-split file with `hello.html#h1-1` The same applies to when there are multiple input files. In order to make the split version be the default for some headers, you can use the <\H splitDefault argument>. This is something that we might consider changing with some option, e.g. keeping the split headers more self contained. But for now, the general feeling is that going to nosplit by default is the best default. = `--stdout` {parent=OurBigBook CLI options} When converting a file, output output to stdout in addition to outputting to a file: `` convert --stdout input.bigb `` The regular output file is also saved. Cannot be used when converting a directory. = `--template` {parent=OurBigBook CLI options} Select a custom https://github.com/harttle/liquidjs[Liquid template] file for the output. If not given, this option defaults to the value of , which if not given defaults to `ourbigbook.liquid.html`. The repository of this documentation for example has a sample `ourbigbook.liquid.html` at: \a[ourbigbook.liquid.html]. If no template is present, the default template at one point was: `` {{ title }} {{ body }} `` This will get out of sync sooner or later with the code, but this should still serve as a good base example for this documentation. Defined variables: * `body`: the rendered body * `dir_relpath`: relative path from the rendered output to the <`_dir` directory>. Sample usage to link to the root directory listing: `` `` * `git_sha`: SHA of the latest git commit of the source code if in a git repository * `github_prefix`: this variable is set only if if the "github" [media provider]. It points to the URL prefix of the provider, e.g. if you have in your : `` "media-providers": { "github": { "remote": "mygithubusername/media" }, `` then you can use media from that repository with: `` `` * `html_ext`: `.html` for local renders, empty for server renders. So e.g. to link to an ID `myid` you can use: `` `` This will ideally be replaced with a more generic link to arbitrary ID mechnism at some point: https://github.com/ourbigbook/ourbigbook/issues/135 * `html_index`: `/index.html` for local renders, empty for server renders * `input_path`: path to the source file relative to the that generated this output, e.g. `path/to/myfile.bigb` May be an empty string in the case of autogenerated sources, notably <`_raw` directory>[automatic directory listings], so you should always check for that with something like: `` {% if input_path != "" %} {% endif %} `` * `is_root_relpath`. Boolean. True if the toplevel being rendered on this output file is the . E.g. in: README.bigb `` = John Smith's homepage == Mathematics `` with conversion, the value of `is_root_relpath` would be: * `index.html`: true * `split.html`: true * `mathematics.html`: false * `root_page`: relative path to the toplevel page, e.g. either `index.html`, `../index.html` locally or `./`, `../` on server oriented rendereing * `root_relpath`: relative path from the rendered output to the toplevel directory. This allows for toplevel resources like CSS to be found seamlessly form inside subdirectories, specially when rendering locally. For example, for the toplevel `main.css` which is generated from \a[main.scss], we can use: `` `` Then, when a file is locally, for example under a subdirectory `mysubdir/myfile.html`, OurBigBook will set: `` root_relpath=../ `` giving the desired: `` `` And if the output path were instead just `myohterfile.html`, `root_relpath` expands to an empty string, giving again the correct: `` `` This will ideally be replaced with a more generic link to arbitrary ID mechnism at some point: https://github.com/ourbigbook/ourbigbook/issues/135 * `raw_relpath`: relative path from the rendered output to the <`_raw` directory>. Should be used to prefix all non- output resources, which is the directory where such files are placed during conversion, e.g. `` `` * `file_relpath`: similar to `raw_relpath`, but link to the <_file output directory> instead * `style`: default OurBigBook stylesheets * `title` We pick Liquid because it is server-side safe: if we ever some day offer a compilation service, Liquid is designed to prevent arbitrary code execution and infinite loops in templates. = Template variable {parent=--template} = `publishTargetIsWebsite` {parent=Template variable} `true` iff the <--publish target> is a standard website, i.e. something that will be hosted publicly on a URL. This is currently `true` for the following publish targets: * `--publish-target github-pages` and it is `false` for the following targets: * `--publish-target local` This template variable is useful to remove JavaScript elements that only work on public websites and not on `localhost` or `file:`, e.g.: * Google Analytics * Giscus = `--title-to-id` {parent=OurBigBook CLI options} Read tiles from stdin line by line on a while loop and output IDs to stdout only, performing conversion on each input line. Sample usage: `` ( echo 'Hello world'; sleep 1; echo 'C++ is great'; sleep 1; echo 'β Centauri' ) | ourbigbook --title-to-id `` outputs: `` hello-world c-plus-plus-is-great beta-centauri `` each with one second intervals between each line. The original application of this option was to allow external non Node.js processes to be able to accurately calculate IDs from human readable titles since the non-ASCII handling of the algorithm is complex, and hard to reimplement accurately. From Python for example one may run something like: `` from subprocess import Popen, PIPE, STDOUT import time p = Popen(['ourbigbook', '--title-to-id'], stdout=PIPE, stdin=PIPE) p.stdin.write('Hello world\n'.encode()) p.stdin.flush() print(p.stdout.readline().decode()[:-1]) time.sleep(1) p.stdin.write('bonne journeé\n'.encode()) p.stdin.flush() print(p.stdout.readline().decode()[:-1]) `` = `--unsafe-ace` {parent=OurBigBook CLI options} {tag=Security} This option enables actions that would allow , so you should only pass it if you trust the repository author. Enabled functionality includes: * = `-w`, `--watch` {id=watch} {parent=OurBigBook CLI options} Don't quit `ourbigbook` immediately. Instead, watch the selected file or directory for changes, and rebuild individual files when changes are detected. Watch every `.bigb` file in an entire directory: `` ourbigbook --watch . `` When a directory is given as the input path, this automatically first does an pass on all files to support . Now you can just edit any OurBigBook file such has `README.bigb`, save the file in your editor, and refresh the webpage and your change should be visible, no need to run a `ourbigbook` command explicitly every time. Exit by entering Ctrl + C on the terminal. Watch a single file: `` ourbigbook --watch README.bigb `` When a single file is watched, the reference database is not automatically updated. If it is not already up-to-date, you should first update it with: `` ourbigbook . `` otherwise you will just get a bunch of undefined ID errors every time the input file is saved. TODO: integrate Live Preview: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/ to also dispense the browser refresh. = `-W`, `--web` {id=web} {parent=OurBigBook CLI options} {tag=Publish your content} = Web upload {synonym} {title2} Sync local directory to instead of doing anything else. To upload the entire repository, run from toplevel: `` ourbigbook --web `` To update just all IDs in a single `physics.bigb` source file use: `` ourbigbook --web physics.bigb `` This requires that all external IDs that `physics.bigb` might depend on have already been previously uploaded, e.g. with a previous `ourbigbook --web` from toplevel. The source code is uploaded, and conversion to HTML happens on the server, no conversion is done locally. This option is not amazing right now. It was introduced mostly to allow uploading the reference demo content from https://cirosantilli.com to https://ourbigbook.com/cirosantilli[], and it is not expected that it will be a major use case for end users for a long time, as most users are likely to just edit on directly. Some important known limitations: * every local file has to be uploaded every time to check if it needs rebuilding or not by comparing old vs new file contents. At we describe a better Git-like Merkle tree method where entire unchanged subtress can be skipped, that will be Nirvana. * file renaming does not work, it will think that you are creating a new file and blows up duplicates * if there's an error in a later file, the database is still modified by the previous files, i.e. there is no atomicity. A way to improve that would be to upload all files to the server in one go, and let the server convert everything in one transaction. However, this would lead to a very long server action, which would block any other incoming request (I tested, everything is single threaded) However, all of those are fixable, and in an ideal world, will be fixed. Patches welcome. = Local header deletion on web upload {parent=web} If you delete a
locally and then do <--web> upload, the article is currently not removed from web. Instead, we simply make its content become empty. The reason for this is that the article may have metadata created by other users such as , which we don't want to delete remove. In order to actually remove the header you should follow the procedure from {full}, which instead first moves all discussions over to a new article before deleting. = `--web-ask-password` {parent=OurBigBook CLI options} Ask for the password in an interactive terminal in case there was a default password that would have otherwise been chosen. Currently the only case where this happens is <`--web-test`> which automatically sets a default `--web-password asdf`. = `--web-dry` {parent=OurBigBook CLI options} <--web> dry run, skip any operations that would interact with the server, doing only all the local preparation required for upload. This is mostly useful for testing the . = `--web-id` {parent=OurBigBook CLI options} Upload only the selected ID with <--web>. That ID must belong to a file being converted for everything to work well. e.g.: `` ourbigbook --web --web-id quantum-mechanics physics.bigb `` = `--web-force-id-extraction` {parent=OurBigBook CLI options} Force on , even if article content is unchanged. The only use case so far for this has been as a hack for incomplete database updates. The correct approach is instead to actually re-extract server side as part of the migration. We should do this by implementing a `Article.reextract` analogous to `Article.rerender`, and a helper {file}. = `--web-force-render` {parent=OurBigBook CLI options} Force remote render of , don't skip it if even if the render is believed to be up-to-date with source. This is analogous to . does not skip the local pre-conversion to split `bigb` format that is done before upload, only the remote render. Conversely, when used together with , does wkip the local bigb conversion, and not the remove one. = `--web-max-renders` {parent=OurBigBook CLI options} Render up to a maxinum of N articles. Useful for quick and dirty , especially together with <--web-force-render> to avoid skipping over finished files. = `--web-nested-set` {parent=OurBigBook CLI options} {disambiguate=option} Update the index of , don't do anything else. Implies <--web>. This option was originally introduced to hep testing bulk nested set updates. = `--web-nested-set-bulk` {parent=OurBigBook CLI options} Only update the index after all articles have been uploaded. There is a complex time tradeoff between using this option or not, which depends on: * how many articles the user has * how many articles are being uploaded This option was initially introduced for uploads. At 104k articles, the bulk update takes 1 minute, but each individual update of an empty article takes about 6 seconds (and is dominated by the nested set update time), making this option an indispensable time saver for the initial upload in that case Therefore in that case, for less than 10 articles you are better off without this option. But with more thatn 10 articles you would want to use it. This rule of thumb should scale for smaller deployments as well however. E.g. at 10k articles, both individual updates and bulk updates should be 10x faster, so the "use this option for 10 or more articles" rule of thumb should still be reasonable. = `--web-password` {parent=OurBigBook CLI options} Set password from CLI. Really bad idea for non-test users with fixed dummy passwords due e.g. to Bash history. = `--web-test` {parent=OurBigBook CLI options} Set defaults for `--web-*` options that are useful for testing locally: `` ourbigbook --web-test `` is equivalent to: `` ourbigbook --web --web-url http://localhost:3000 --web-user barack-obama --web-password asdf `` You can also override those defaults by just specifying them normally, e.g. to do a different user: `` ourbigbook --web-test --web-user donald-trump `` = `--web-url` {parent=OurBigBook CLI options} Set a custom URL for from the command line. If not given, the canonical https://ourbigbook.com is used. This option is used e.g. for testing locally e.g. with: `` ourbigbook --web --web-url http://localhost:3000 `` Also consider for local testing. = `--web-user` {parent=OurBigBook CLI options} Set the username for from the command line, e.g.: `` ourbigbook --web --web-url http://localhost:3000 --web-user barack-obama `` If not given: * use the latest previous successfull web login with `ourbigbook --web` if there are any. In that case, the CLI informs you with a message of type: `` Using previous username: barack-obama `` * otherwise, you will be prompted for it from the command line. = `ourbigbook.json` {parent=OurBigBook CLI} {scope} OurBigBook configuration file that affects the behaviour of ourbigbook for all files in the directory. `ourbigbook.json` not used for input from , since we are mostly doing quick tests in that case. While `ourbigbook.json` is optional, it is used to determine the toplevel directory of a OurBigBook project, which has some effects such as those mentioned at . Therefore, it is recommended that you always have a `ourbigbook.json` in your project's toplevel directory, even if it is going to be an empty JSON containing just: `` {} `` For example, if you convert a file in a subdirectory such as: `` ourbigbook subdir/notindex.bigb `` then `ourbigbook` walks up the filesystem tree looking for `ourbigbook.json`, e.g.: * is there a `./subdir/ourbigbook.json`? * otherwise, is there a `./ourbigbook.json`? * otherwise, is there a `../ourbigbook.json`? * otherwise, is there a `../../ourbigbook.json`? and so on. If we reach the root path `/` and no `ourbigbook.json` is found, then we understand that there is no `ourbigbook.json` file present. = `dontIgnore` {parent=ourbigbook.json} List of . If a file path matches any of them, then override <`ignore`> and don't ignore the path. E.g., if you have several `.scss` examples that you don't want to convert, but you do want to convert the `main.scss` for the website itself: `` "ignore": [ ".*\\.scss" ] "dontIgnore": [ "main.scss" ] `` Note however that if an upper directory is ignored, then we don't recurse into it, and `dontIgnore` will have no effect. = `dontIgnoreConvert` {parent=ourbigbook.json} Analogous to but acts on rather than . = `ignore` {parent=ourbigbook.json} List of paths relative to the that will ignore, unless it also has a match in <`dontIgnore`>. Each entry is a , and it must match the entire path from start to end to count. If a directory is ignored, all its contents are also automatically ignored. Useful if your project has a large directory that does not contain OurBigBook sources, and you don't want OurBigBook to mess with it. Only ignores recursive conversions, e.g. given: `` "ignore": [ "web" ] `` doing: `` ourbigbook . `` skips that directory, but `` ourbigbook web/myfile.bigb `` converts it because it was explicitly requested. Examples: * ignore all files with a given extension; `` "ignore": [ ".*\\.tmp", ] `` Yes, it is a bit obnoxious to have to escape `.` and the backslash. We should use some proper globbing library like: https://github.com/isaacs/node-glob[]. But on the other hand makes this mostly useless, as `.gitignore` will be used most of the time. TODO: also ignore during . = `ignoreRender` {parent=ourbigbook.json} Similar to , but only ignore the files from rendering converesions such as bigb -> html, scss -> css. Unlike , matching files are still placed under the <`_raw` directory> and can be publicly viewed. You almost always want this option over , with files that should not be in the repository being just ignored with your `.gitignore` instead: {full}. = `ourbigbook.json` `id` {id=id} {parent=ourbigbook.json} Dictionary of options that control generation. = `id` `normalize` `latin` {parent=id} If `true`, does on the title. Default: `true`. = Latin normalization {c} {parent=id normalize latin} ASCII normalization is a custom OurBigBook defined normalization that converts many characters that look like Latin characters into Latin characters. For now, we are using the `deburr` method of Lodash: https://lodash.com/docs/4.17.15#deburr[], which only affects Latin-like characters. In addition to `deburr` we also convert: * en-dash and em-dash to simple ASCII dash `-`. Wikipedia Loves en-dashes in their article titles! * greek letters are replaced with their standard latin names, e.g. `α` to `alpha` One notable effect is that it converts variants of ASCII letters to ASCII letters. E.g. `é` to `e` removing the accent. This operation is kind of a superset of Unicode normalization acting only on Latin-like characters, where Unicode basically only removes things like diacritics. OurBigBook normalization on the other also does other natural transformations that Unicode does not do, e.g. `æ` to `ae` as encoded by `deburr` and further custom replacements. TODO `lodash.deburr`: * only deals with Unicode blocks "https://en.wikipedia.org/wiki/Latin-1_Supplement[Latin-1 Supplement]" and "https://en.wikipedia.org/wiki/Latin_Extended-B[Latin Extended-A]", notably missing https://en.wikipedia.org/wiki/Latin_Extended-B[Latin Extended-B], https://en.wikipedia.org/wiki/Latin_Extended-C[C] and https://en.wikipedia.org/wiki/Latin_Extended-D[D], which contain some important characters. Pull requests have been ignored: * https://github.com/lodash/lodash/issues/4530 * https://github.com/lodash/lodash/pull/5491 so maybe we should just code our own on top. * misses some candidates in https://en.wikipedia.org/wiki/Letterlike_Symbols[letterlike symbols] * https://en.wikipedia.org/wiki/Mathematical_operators_and_symbols_in_Unicode#Mathematical_Operators_block[mathematical operators block] Bibliography: * https://stackoverflow.com/questions/990904/remove-accents-diacritics-in-a-string-in-javascript * https://github.com/ourbigbook/ourbigbook/issues/162 = `id` `normalize` `punctuation` {parent=id} If `true`, does on the title. Default: `true`. = Punctuation normalization {c} {parent=id normalize punctuation} Some selected punctuation marks are automatically converted into their dominant corresponding pronunciations. These are: * `%`: `percent` * `&`: `and` * `+`: `plus` * `@`: `at` * `−` (Unicode minus sign, U+2212, distinct from the ASCII hyphen): `minus` Dashes are added around the signs if needed, e.g.: * `C++`: `c-plus-plus` * `Q&A`: `q-and-a` * `Folding@home`: `folding-at-home` = `lint` {parent=ourbigbook.json} Dictionary of lint options to enable. OurBigBook tries to be strict about forcing specific styles by default, e.g. forbids triple newline paragraph. But sometimes we just can't bear it :-) = `lint` `h-parent` {parent=lint} Possible values: * `parent`: forces headers to use <\H parent argument> to specify their level * `number`: forces headers to not use <\H parent argument> to specify their level, i.e. to use a number or a number of `=` You should basically always set either one of those on any serious project. Forgetting a `parent=` in a project that uses `parent=` everywhere else is a common cause of build bugs, and can be hard to debug without this type of linting enabled. = `lint` `h-tag` {parent=lint} Possible values: * `child`: forbids from using the <\H tag argument>. They should instead use the <\H child argument>. * `tag`: forbids from using the <\H child argument>. They should instead use the <\H tag argument>. = `h` {parent=ourbigbook.json} {scope} This dictionnary stores options related to headers. = `numbered` {parent=h} Sets the default <\H numbered argument> argument of the toplevel headers of each source file. Note that since the option is inherited by descendants, this can also affect the rendering of ancestors. https://github.com/ourbigbook/ourbigbook/issues/188 contains a proposal to instead inherit this property across . If you set this ourbigbook.json option: `` { "h": { "numbered": true } } `` it is possible to override it for a specific file with and explicit `=0` <\H numbered argument>: `` = Not numbered exception {numbered=0} == Child also inherits not numbered `` Make every link to something that is not on the current page open on a new tab instead of the current one, i.e. add `target="_blank"` to such links. = `splitDefault` {parent=h} This options is exactly analogous to the option, but it affects the <\H splitDefault argument> instead of the <\H numbered argument>. = `splitDefaultNotToplevel` {parent=h} If given, the toplevel output of each input source is always non-split, and a split version is not generated at all. This of course overrides the <\H splitDefault argument> for toplevel headers, making any links go to the non split version, as we won't have a split version at all in this case. E.g.: ourbigbook.json `` { "h": { "splitDefault": true, "splitDefaultNoToplevel": true, } } `` my-first-header.bigb `` = My first header == My second header `` When converted with: `` ourbigbook --split-headers my-first-header.bigb `` would lead only to two output files: * my-first-header: not split * my-second-header: split Without `splitDefaultNoToplevel` we would instead have: * my-first-header: split * my-first-header-nosplit: not split * my-second-header: split The initial use case for this was in . If we didn't do this, then there would be two versions of every article at the toplevel of a file: split and nosplit. This would be confusing for users, who would e.g. see two new articles on the article index every time they create a new one. It would also mean that metadata such as comments would be visible in two separate locations. So instead of filtering the duplicate articles on every index, we just don't generate them in the first place. = `htmlXExtension` {parent=ourbigbook.json} If `false`, implies <--no-html-x-extension>. The initial application of this option was to {full}. = `media-providers` {parent=ourbigbook.json} The `media-providers` entry of `ourbigbook.json` specifies properties of how media such as and are retrieved and rendered. The general format of `media-providers` looks like: `` "media-providers": { "github": { "default-for": ["image"], // "all" to default for both image, video and anything else "path": "data/media/", // data is gitignored, but should not be nuked like out/ "remote": "ourbigbook/ourbigbook-media" }, "local": { "default-for": ["video"], "path": "media/", }, "youtube": {} } `` Properties that are valid for every provider: * `default-for`: use this provider as the default for the given types of listed macros. The first character of the macros are case insensitive and must be given as lower case. Therefore e.g.: * `image` applies to both `image` and `Image` * giving `Image` is an error because that starts with an upper case character * `title-from-src` (`bool`): extract the `title` argument from the `src` by default for media such as and as if the `titleFromSrc` macro argument had been given, see also: {full} Direct children of media-providers and subproperties that are valid only for them specifically: * `local`: tracked in the current Git repository as mentioned at {full} * `path`: location of the cloned local repository relative to the root the main repository * `github`: tracked in a separate Git repository as mentioned at {full} * `path`: analogous to `path` for `local`: a local location for this GitHub provider, where the repository can optionally be cloned. When not during a run with the <--publish option>, OurBigBook checks if the path exists locally, and if it does, then it uses that local directory as the source intead of the GitHub repository. This allows you to develop locally without Internet and see the latest version of the images without pushing them. During publishing, the GitHub version is used instead. TODO make this even more awesome by finishing to implement https://github.com/ourbigbook/ourbigbook/issues/184[]: * automatically `git push` this repository during deployment to ensure that any asset changes will be available. * ignore the path from OurBigBook conversion as if added to , and is not added to the final output, because you are already going to have a copy of it. This way you can use the sanes approach which is to track the directory as a Git submodule as mentioned at: , instead of either: * keeping it outside of the repository * keeping it in the repository but explicitly ignoring it as well, which is a bit redundant * `remote`: `/` * `youtube`: YouTube See also: https://github.com/ourbigbook/ourbigbook/issues/40 = `openLinksOnNewTabs` {parent=ourbigbook.json} = `outputOutOfTree` {parent=ourbigbook.json} Default: `true` If `true` place the HTML output under at `out/html`. For example with: `` { "outputOutOfTree": false } `` then `` ourbigbook hello.bigb `` would be place its output under: `` hello.html `` instead of `out/html/hello.html`. Advantages of `outputOutOfTree=true`: * the source tree becomes cleaner, especially when using which can produce hundreds of output files from a single input file * if you want to track several `.html` source files in-tree, you don't need to add an exception to each of of them on the `.gitignore` as: `` *.html !/ourbigbook.liquid.html `` Disadvantages: * you have to type more to open each output file on the terminal This option is always forced to `false` when is given. Implemented at: https://github.com/ourbigbook/ourbigbook/issues/163 = `prepublish` {parent=ourbigbook.json} Path of a script that gets executed after conversion, and before upload, when running with the <--publish option>. The script arguments are: * the publish output directory. That directory is guaranteed to exist when `prepublish` is called. For `git`-based publish targets, all files are almost ready in there, just waiting for a `git add .` that follows `prepublish`. This means that you can use this script to place or remove files from the final publish output. If the `prepublish` script returns with a non-zero exit value, the publish is aborted. = `publishCommitDate` {parent=ourbigbook.json} If given, use this fixed date as the author and comitter date of the publish commit. All Git date formats are accepted as documented in `man git-commit`, e.g. `2005-04-07T22:13:13`. = `publishOptions` {parent=ourbigbook.json} options that should be used only on the published output when publishing with the <--publish option>. If given these options override pre-existing options on the published output. Only options that get passed to currently take effect, options that affect e.g. only the <`ourbigbook` executable> don't work currently. Lazy. = `publishRemoteUrl` {parent=ourbigbook.json} A custom `remoteUrl` to push build outputs to. If not given this value is extracted by default from the `origin` remote of the Git repository were the source code is located in. = `redirects` {parent=ourbigbook.json} Generate custom redirects. For example: `` "redirects": [ ["cirodown", "ourbigbook"] ], `` produces a file in the output called `cirodown.html` that redirects to `ourbigbook.html`. Absolute URLs are also accepted, e.g.: `` "redirects": [ ["ourbigbook", "https://docs.ourbigbook.com"] ], `` produces a file in the output called `ourbigbook.html` that redirects to `https://docs.ourbigbook.com`. When dealing with regular , you generally don't want to use this option and instead use the <\H synonym argument>, which already creates the redirection for you. This JSON option can be useful however for dealing with things that are outside of your OurBigBook project. For example, at one point, this project renamed the repository https://github.com/cirosantilli/cirodown[] to https://github.com/ourbigbook/ourbigbook[]. Unfortunately, GitHub Pages does not generate redirects like github.com itself. So in this case, we've added to the of the toplevel user repository https://github.com/cirosantilli/cirosantilli.github.io the lines: `` "redirects": [ ["cirodown", "ourbigbook"] ], `` which produces a file in the output called `cirodown.html` that redirects to `ourbigbook.html`. In this case, `cirodown` and `ourbigbook` don't have to be any regular IDs present in the database, those strings are just used directly. TODO ideally we should check for conflicts with regular output from split headers IDs or their synonyms. But lazy. = `template` {parent=ourbigbook.json} Select the template Liquid file to use. Serves as the default for the <--template>. If this option is not given, and if a file `ourbigbook.liquid.html` exists in the project, then that file is used. If `ourbigbook.liquid.html` exists but you don't want to use it, set the option to `null` and it won't be used. = `toSplitHeaders` {parent=ourbigbook.json} Make every point to the version of the pages of the website. Do this even if those pages don't exist, or if they are not the default target e.g. as per the <`\H` `splitDefault` argument>. The initial application of this option was to {full}. If this option is set, then nosplit/split header metadata links are removed, since it was hard to come up with a sensible behaviour to them, and it won't matter on web redirection where every page is nonsplit anyways. = `web` {parent=ourbigbook.json} {scope} This dict contains options related to interaction between and deployments. = `host` {parent=`web`} Select the default host used for * publishing. Serves as the default domain for <--web-url> * where it is used, e.g. Defaults to `ourbigbook.com`, the [reference Web instance]. = `hostCapitalized` {parent=`web`} Capitalized version of <`host`>, e.g. `OurBigBook.com`. Default: * if <`host`> is given, use it * otherwise, `OurBigBook.com` Shows up on as a potentially more human readable version of the hostname. = `linkFromHeaderMeta` {parent=`web`} Type: boolean. Default: `false`. If `true`, adds a link under the metadata section of every header of a static website pointing to the corresponding article on . It also sends you to Heaven for supporting the project. This option requires <`username`> to be set. For example, if you set: `` "web": { "username": "myusername", "linkFromHeaderMeta": true } `` then in the rendering of a README.bigb: `` = Index == My h2 {scope} === My h2 2 {scope} `` those headers would have a metadata entry pointing respectively to: * `https://ourbigbook.com/myusername` * `https://ourbigbook.com/myusername/my-h2` * `https://ourbigbook.com/myusername/my-h2/my-h2-2` In order for such links not to be broken, you should always first do a to ensure that the articles are present on . = `username` {parent=`web`} Type: string. Sets your username. This is used e.g. by . = `xPrefix` {parent=ourbigbook.json} If given, prepend the given string to every single output. The initial application of this option was to {full}. E.g. suppose that you previously had at `myoldsite.com` you had: animal.bigb `` = Animal don't eat . == Dog `` plant.bigb `` = Plant == Banana `` Originally that would render as: `` Dogs don't eat bananas. `` But then if you set in `ourbigbook.json`: `` { "xPrefix": "https://mynewsite.com/" } `` it will instead render as: `` Dogs don't eat bananas. `` where: * dogs: untouched as it links to the same page as the current one * bananas: the prefix is added, as it is on another page are automatically resolved so that they will also be present in the target. E.g. in: subdir/notindex.bigb `` `` subdir/notindex2.bigb `` = Notindex2 `` we get on `subdir/notindex.html`: `` `` and not: `` `` = Redirect from a static website to a dynamic website {c} {parent=OurBigBook CLI} This section describes how to generate mass redirects from a such as https://cirosantilli.com to a dynamic website such as https://ougbook.com/cirosantilli[]. The use case of this is if you are migrating from one domain to another, and want to keep old files around to not break links, but would rather redirect users to the new preferred pages instead to gather PageRank there. This happened in our case when Ciro felt that had reach enough maturity to be a reasonable reader alternative to the static website. Basically what you want to do in that case is to use the following options: * * * * as in: `` "publishOptions": { "toSplitHeaders": true, "htmlXExtension": false, "xPrefix": "https://ourbigbook.com/cirosantilli/" }, `` = Ignored files {c} {parent=OurBigBook CLI} The following files are ignored from conversion: * patterns * gitignored files: {full} * a few hardcoded basenames, such as `.git` and , see `DEFAULT_IGNORE_BASENAMES` in \a[ourbigbook] Note that this applies even if you try to convert a single ignored file such as: `` ourbigbook ignored.bigb `` We are strict about this in order to prevent accidentally polluting the database with temporary data. = Ignore from `.gitignore` {parent=Ignored files} If the project is a , the standard `git` ignore rules are used for ignores. This includes `.git/info/exclude`, `.gitignore` and the user's global gitingnore file if any. = Parallel build {c} {parent=OurBigBook CLI} TODO: get this working. Maybe we should also bake it into the `ourbigbook` CLI tool as well for greater portability. Starting like this as a faster way to prototype: `` rm -rf out/parallel mkdir -p out/parallel # ID extraction. git ls-files | grep -E '\.bigb$' | parallel -X ourbigbook --no-render --no-check-db --outdir 'out/parallel/{%}' '{}' ./merge-dbs out/db.sqlite3 out/parallel/*/db.sqlite3 ourbigbook --check-db # Render. git ls-files | grep -E '\.bigb$' | parallel -X ourbigbook --no-check-db '{}' `` Observed `--no-render` speedup on 1k small files from the and 8 cores: 3x. So not bad. Observed render speedup on 1k small files from the and 8 cores: none. TODO. Is this because of database contention? = OurBigBook Library {c} {parent=OurBigBook} = JavaScript API {c} {synonym} {title2} The main entry point for the JavaScript API is the `ourbigbook.convert` function. An example can be seen under \a[lib_hello.js]. Note that while doing a simple conversion is easy, things get harder if you want to take multi-file features in consideration, notably . This is because these features require interacting with the , and we don't do that from the default `ourbigbook.convert` API because different deployments will have very different implementations, notably: * local Node.js run uses SQLite, an implementation can be seen in the \a[ourbigbook] file class `SqlDbProvider` * the in-browser version that runs in the browser editor of the makes API calls to the server = OurBigBook Library environemnt variable {c} {parent=OurBigBook Library} These are variables that affect the itself, and therefore also get picked up by and . = OurBigBook environment variable true {parent=OurBigBook Library environemnt variable} For boolean environment variables, the value of "true" should use be `1`, e.g. as in: `` OURBIGBOOK_POSTGRES=1 ./bin/generate-demo-data.js `` Every other value is considered false, including e.g. `true`. = OurBigBook Web {c} {parent=OurBigBook} = Dynamic website {synonym} {title2} OurBigBook Web is the software program that powers https://OurBigBook.com[], its official flagship instance, see also: {full}. is currently the main tool developed by the . This section contains both [end user documentation] and [developer documentation]. More subjective rationale, motivation and planning aspects of the project are documented at: https://cirosantilli.com/ourbigbook-com[]. = OurBigBook Web user manual {c} {parent=OurBigBook Web} is a bit like Wikipedia, but where each user can have their own version of each page, and it [cannot be edited by others without permission]. The goal of the is to make university students write perfect natural sciences books for free as they are trying to learn for their lectures. Suppose that Mr. Barack Obama is your calculus teacher this semester. Being an enlightened teacher, Mr. Obama writes everything that he knows on his OurBigBook.com account. His home page look something like the following tree: * https://ourbigbook.com/barack-obama[]: Obama's toplevel index pages linking to all his pages * https://ourbigbook.com/barack-obama/mathematics[Mathematics] * https://ourbigbook.com/barack-obama/calculus[Calculus] * https://ourbigbook.com/barack-obama/derivative[Derivative] * https://ourbigbook.com/barack-obama/integral[Integral] * https://ourbigbook.com/barack-obama/fundamental-theorem-of-calculus[Fundamental theorem of calculus] * https://ourbigbook.com/barack-obama/algebra[Algebra] * https://ourbigbook.com/barack-obama/physics[Physics] On your first day of class, Mr. Obama tells his students to read the "Calculus" section, ask him any questions that come up online, and just walks away. No time wasted! While you are working through the sections under "Calculus", you happen to notice that the "Fundamental theorem of calculus" article is a bit hard to understand. Mr. Obama is a good teacher, but no one can write perfect tutorials of every little thing, right? This is where OurBigBook comes to your rescue. There are two ways that it can help you solve the problem: * * = OurBigBook Web topics {c} {parent=OurBigBook Web user manual} = OurBigBook Web topic {c} {synonym} = Topic {synonym} Topics group articles that have the same title by different users. This feature allows you to find the best article for a given topic, and it is one of the key innovations of . Topics are a bit like Twitter hashtags or Quora questions: their goal is to centralize knowledge about a specific subject by different people at a single location. \Video[https://www.youtube.com/watch?v=54nxjC9BWTg] {title= demo} {height=700} {width=700} \Image[Integral_by_Barack_showing_fundamental_theorem_of_calculus_child_topic.png] {height=600} {border} {provider=github} {description= https://ourbigbook.com/barack-obama/integral#barack-obama/fundamental-theorem-of-calculus[Mr. Obama's article about the fundamental theorem of calculus] was not very good, and we were left clueless. But we can see that there are 3 articles in total about "Fundamental theorem of calculus", 2 of them by other authors, so maybe one of the others will help! } \Image[Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png] {border} {provider=github} {height=600} {description= After clicking that button, we reach <#fundamental theorem of calculus>[the "Fundamental theorem of calculus" topic page]. Here we see that there are 3 articles in total. The one by Mr. Trump has 1 vote, while the others have zero, so Trump's appears on top. So maybe that is the best one! After a quick read, it does look like it might be interesting. Let's click on "Read the full article" to also see the descendant articles by Mr. Trump. } \Image[Fundamental_theorem_of_calculus_by_Donald_Trump.png] {border} {height=600} {provider=github} {description= This leads us to https://ourbigbook.com/donald-trump/fundamental-theorem-of-calculus[Mr. Trump's version of the fundamental theorem page]. That's clearly, a superior article that will enlighten our problem. Donald must either be a very talented teacher or a hard working student from some other university. Thanks Mr. Trump! } = Create your own article about a topic in OurBigBook Web {c} {parent=OurBigBook Web topics} If even existing [topics] and [discussions] have failed you, and you have finally understood a subject after a few hours of Googling, why not share your knowledge by creating a new article yourself? There are a few ways to do that. \Image[Fundamental_theorem_of_calculus_topic_page_new_article.png] {border} {provider=github} {height=500} {description=One easy way to create an article about a given topic is to use the "New Article in Topic" button from the topic page. URL: https://ourbigbook.com/go/topic/fundamental-theorem-of-calculus[]} \Image[Fundamental_theorem_of_calculus_subheader_create_my.png] {border} {provider=github} {height=200} {description=Another option is to click the "Create my version of this topic button". URL: https://ourbigbook.com/barack-obama/mathematics#fundamental-theorem-of-calculus[]} \Image[Fundamental_theorem_of_calculus_editor_new.png] {border} {provider=github} {height=300} {description=If you click do any of the above links, you will be redirected to the editor page, and the title will be preset. By simply using that exact same title to create your new article, your article will then appear in the correct "Fundamental theorem of calculus" topic where others might see it. https://ourbigbook.com/go/new?title=Proof%20of%20the%20fundamental%20theorem%20of%20calculus[].} = OurBigBook Web dynamic article tree {c} {parent=OurBigBook Web user manual} = Dynamic article tree {synonym} implements what we call "dynamic article tree". What this means is that, unlike the static website generated by where you know exactly which headers will show as children of a given header, we just dynamically fetch a certain number of descendant pages at a time. As an example of dynamic artic tree, note how the article "Special relativity" can be seen in all of the following pages: * https://ourbigbook.com/barack-obama/special-relativity as the toplevel article * https://ourbigbook.com/barack-obama/physics as a child * https://ourbigbook.com/barack-obama/natural-science as the child of a child The only efficient way to do this is to pick which articles will be rendered as soon as the user makes the request, rather than having fully pre-rendered pages, thus the name "dynamic". \Video[https://www.youtube.com/watch?v=sX_D_5tCQgg] {title= demo} {height=700} {width=700} The design goals of the dynamic article tree are to produce articles such that: * each article can appear as the toplevel article of a page to get better SEO opportunities * and that page that contains the article can also contain as many descedants as we want to load, not jus the article itself, so as to not force readers to click a bunch of links to read more For example, with a static website, a user could have a page structure such as: natural-science.bigb `` = Natural science == Physics \Include[special relativity] `` special-relativity.bigb `` = Special relativity == Lorentz transformation `` In the static output, we would have two output files with multiple pages: * `natural-science.html` * `special-relativity.html` plus one split output file for each header if were enabled: * `natural-science-split.html` * `physics.html` * `special-relativity-split.html` * `lorentz-transformation.html` In this setup the header "Physics" for example is present in one of two possible pages: * `natural-science.html`: as a subheader, but Special Relativity is not shown even though it is a child * `physics.html`: as the top header, and Special Relativity is still not shown as we are in split mode In the case of the dynamic article tree however, we achieve our design goals: * "Physics" is the toplevel header, and therefore can get much better SEO * "Special Relativity", "Lorentz transformation" and any other descendants will still show up below it, so it is much more readable than a page We then just cut off at a certain number of articles to not overload the server and browsers on very large pages. Those pages can still be accessed through the ToC, which is currently unlimited. We also want to implement: to allow users to click to load more articles. And all of that is achieved: * without requiring authors to manually determine which headers are toplevel or not to customize page splits with reasonable load sizes. * without keeping multiple copies of the render output of each page and corresponding pre-rendered ToCs. On the static website, we already had two rendering for each page: one split and one non-split, and the ToCs were huge and copied everywhere. Perhaps the ToC side could be resolve with some runtime fetching of static JSON, but then that is bad for SEO. The downside of the feature is slightly slower page loads and a bit more server workload. We have kept it quite efficient server-side by implementing the page fetching with a implementation. We believe that dynamic article treee offers a very good tradeoff between server load, load speeds, SEO, readability and author friendliness. = OurBigBook Web discussions {c} {parent=OurBigBook Web user manual} Each article has their own discussion section. This way you can easily see if other students have had the same problem as you and asked about it already. \Image[Fundamental_theorem_of_calculus_subheader_discussion.png] {border} {height=200} {provider=github} {description=Click the "Discussions" button to see if other people hit the same problem as you and created a discussion thread for it. We see that there are 3 total discussions about this header, so let's check them out. URL: https://ourbigbook.com/barack-obama/mathematics#fundamental-theorem-of-calculus[]} \Image[Fundamental_theorem_of_calculus_by_Barack_Obama_discussions.png] {border} {height=300} {provider=github} {description=From these 3 recent threads, the first one has one like, and it seems that someone found the same difficulty that we did. URL: https://ourbigbook.com/go/issues/barack-obama/fundamental-theorem-of-calculus[]} \Image[Fundamental_theorem_of_calculus_by_Barack_Obama_discussion_1.png] {border} {height=600} {provider=github} {description=So let's inspect that discussion. Ah, clearly, the comments are very illuminating, our problem is solved! URL: https://ourbigbook.com/go/issue/1/barack-obama/fundamental-theorem-of-calculus[]} = OurBigBook Web editor {c} {parent=OurBigBook Web user manual} {tag=Publish your content} comes with a browser text editor where users can create and edit their articles in . This is for example the editor you see when creating a new article at: https://ourbigbook.com/go/new One day want to add an option to have a visual editor: {full}, but for now we'll try to make the text-editor as awesome as we can. = Create a child article in OurBigBook Web {c} {parent=OurBigBook Web editor} Marking a page as the child of another page is easy in : you can simply set the parent of the page directly on the editor UI. If you don't want the article to be the first child of a parent, you can also set the "previous sibling" field. This specifies after which article the new article will be inserted. \Video[https://www.youtube.com/watch?v=yQRjLyqILl0] {title= parent selection on the web UI} {height=700} {width=700} \Video[https://www.youtube.com/watch?v=2Ne6AorMbGM] {title= error reporting} {height=700} {width=1000} {description=Note that
. You should use the packaged `_obb/ourbigbook_runtime.js` instead of this file directly however. = JavaScript redirect to split on missing ID {c} {parent=Runtime feature} When you have a document like: animal.bigb `` = Animal == Dog === Poodle `` the version without will contains a valid ID within it: `` animal.html#poodle `` However, if at some point you decide that the section `dog` has become too large and want to split it as: `` = Animal \Include[dog] `` and: dog.bigb `` = Dog == Poodle `` When you do this, it would break liks that users might have shared to `animal.html#poodle`, which is not located at `dog.html#poodle`. To make that less worse, if are enabled, we check at runtime if the ID `poodle` is present in the output, and if it is not, we redirect to the split page `#poodle` to `poodle.html`. It would be even more awesome if we were able to redirect to the non-split version as well, `dog.html#poodle`, but that would be harder to implement, so not doing it for now. = Tooling {parent=OurBigBook} Unlike all languages which rely on ad-hoc tooling, we will support every single tool that is required and feasible to be in this repository in this repository, in a centralized manner. = Conversion to/from other formats {parent=Tooling} The only thing we have for now is the quick and dirty \a[adoc-to-ciro]. The better approach would be to implement a converter in Haskell from anything to OurBigBook. And from OurBigBook to anything, create new output formats inside OurBigBook to those other formats. = Editor support {parent=Tooling} = Visual Studio Code {parent=Editor support} = VS Code {synonym} {title2} VS Code is intended to be the best supported OurBigBook editor. The official OurBigBook extension is published at: https://marketplace.visualstudio.com/items?itemName=ourbigbook.ourbigbook-vscode[] by the publisher account: https://marketplace.visualstudio.com/publishers/ourbigbook[]. Its source code is located under \a[vscode]. Currently, the extension it only supports syntax highlighting, but we want to support everything you would expect from proper programming language support, notably: * deployment as or to * build with click to line stdout error parsing * jump to ID definitions * HTML preview, maybe we should learn from the Asciidoc extension Historically, support came first and was better developed. But that was just an ad-hoc path of least resistance, VS Code is the one we are going to actually support moving forward. Our syntax highlighting attempts mostly to follow the official HTML style, which is perhaps the best maintained data-language. We have also had a look at the LaTeX, Markdown and Asciidoctor ones for refernce. One current fundamental limitation of VS Code is that there is no way to preview images and mathematics inline with text: https://stackoverflow.com/questions/52709966/vscode-is-it-possible-to-show-an-image-inside-a-text-buffer If only it were able to do that, it would go a long way to being as good as a WYSIWYG interface. \Video[https://www.youtube.com/watch?v=Ghvlztiu6rI] {title=Edit locally and publish demo} {description=This shows editing and it using the extension.} {disambiguate=Visual Studio Code} {height=720} {width=720} = Vim {parent=Editor support} You can install the support with https://github.com/VundleVim/Vundle.vim[Vundle] with: `` set nocompatible filetype off set rtp+=~/.vim/bundle/Vundle.vim call vundle#begin() Plugin 'gmarik/vundle' let g:snipMate = {} let g:snipMate.snippet_version = 1 Plugin 'MarcWeber/vim-addon-mw-utils' Plugin 'tomtom/tlib_vim' Plugin 'garbas/vim-snipmate' Plugin 'ourbigbook/ourbigbook', {'rtp': 'vim'} `` or by directly dropping the files named below under your `~/.vim/`, e.g. `vim/syntax/ourbigbook.vim` The following support is provided: * \a[vim/syntax/ourbigbook.vim]: syntax highlighting. As for other programming languages, this cannot be perfect without actually parsing, which would be slow for larger files. But even the imperfect approximation already covers a lot of the most cases. Notably it turns off spelling from parts of the document like URLs and code which would otherwise contain many false positive spelling errors. * \a[vim/snippets/ourbigbook.snippets]: snippets for https://github.com/honza/vim-snippets[], which you also have to install first for them to work. For example, with those snippets installed, you can easily create links to headers. Suppose you have: `` = My long header `` To create an cross reference to it you can: * copy `My long header` to the clipboard, see copy to clipboard shortcuts at: https://stackoverflow.com/questions/3961859/how-to-copy-to-clipboard-in-vim/67890119#67890119 * type `\x` and then hit tab and it will automatically expand to: `` \x[my-long-header] `` This provides a reasonable alternative for ID calculation, until a ctags-like setup gets implemented (never/-only? ;-)) Similarly for <\H parent argument> you can do: `` {p `` would expand to: `` {parent=my-long-header} `` Syntax highlighting can likely never be perfect without a full parser (which is slow), but even the imperfect approximate setup (as provided for most other languages) is already a huge usability improvement. We will attempt to err on the side of "misses some stuff but does not destroy the entire page below" whenever possible. * mappings: * `f`, which usually means `,f` (comma then F): start searching for a header in the current file. Does a regular `/` search without opening any windows, to is it very ligthweight. Mnemonic: "Find". * `h` (requires https://github.com/tpope/vim-fugitive[Fugitive] to be installed): sets up the `ObbGitGrep` command, which searches for header across all git tracked files in the current Git repository. After `,g` you are left in the prompt with: `` ObbGitGrep `` so if you complete that by: `` ObbGitGrep animal kingdom `` it will match headers that start with `animal kingdoom` case insentively, e.g.: `` = Animal kingdom tree = Animal kingdom book `` Vim regular expressions are accepted, e.g. if you don't want it to start with the search pattern: `` ObbGitGrep .*animal kingdom `` The command opens a new tab (technically a "Vim error window") containing all matches, where you can click Enter to open one of them. Mnemonic: "Header search". A simple way to develop is to edit the Vundle repository directly under `~/.vim/bundle/ourbigbook`. = Browser editor with preview {parent=Editor support} There are two versions of this editor: * \a[editor.html] is a toy/demo with no backing database. That editor can be viewed directly locally with: `` git clone https://github.com/ourbigbook/ourbigbook cd ourbigbook npm install npm run build-assets chrome editor.html `` It also appears at https://docs.ourbigbook.com/editor[] hosted simply under GitHub pages. * a similar looking editor will also appear on the , but this time linked to the database. That more advanced editor will actually save results back to the database, and show allow preview of features such as linking to headers of other pages. Issues for the editor are being tracked under: https://github.com/ourbigbook/ourbigbook/labels/editor We must achieve an editor setup with synchronized live side-by-side preview. Likely, we will first do a non WYSIWYG editor with side by side preview with scroll sync. Then, if the project picks up steam, we can start considering a full WYSIWYG. It would be amazing to have a WebKit interface that works both on browser for the and locally. Possibilities we could reuse: * CKeditor https://ckeditor.com/ Used e.g. by Trilium Notes. * Editor.js Returns JSON AST! * website: https://editorjs.io/ * source: https://github.com/codex-team/editor.js * WYSIWYG: yes * preview scroll sync: yes * StackEdit * markup implementation: PageDown * website: https://stackedit.io * source: https://github.com/benweet/stackedit * demo: https://stackedit.io/app * WYSIWYG: no * preview scroll sync: yes * Editor.md * website: https://github.com/pandao/editor.md * source: https://github.com/pandao/editor.md * demo: https://pandao.github.io/editor.md * WYSIWYG: no * preview scroll sync: yes but buggy when tested 2019-12-12 on live website * https://github.com/markdown-it/markdown-it[markdown-it] Custom editor and highlight via https://github.com/highlightjs/highlight.js/[highlight.js]. * markup implementation: custom * website: https://markdown-it.github.io * source: https://github.com/markdown-it/markdown-it * WYSIWYG: no * preview scroll sync: yes * editor hangs on large input: yes * Quill.md * website: https://quilljs.com * source: https://github.com/quilljs/quill/ * demo: https://pandao.github.io/editor.md * WYSIWYG: yes * markdown output: no https://github.com/quilljs/quill/issues/74 * https://ui.toast.com/tui-editor/ * https://www.froala.com/wysiwyg-editor = Error reporting {parent=Tooling} A lot of effort has been put into making error reporting as good as possible in OurBigBook, to allow authors to quickly find what is wrong with their source code. Error reporting is for example tested with `assert_error` tests in \a[test.js]. Please report any error reporting bug you find, as it will be seriously tracked under the: https://github.com/ourbigbook/ourbigbook/issues?q=label%3Aerror-reporting+[`error-reporting` label]. Notably, OurBigBook should never throw an exception due to a syntax error, as that prevents error messages from being output at all. = Order of reported errors {parent=Error reporting} One important philosophy of the error reporting is that the very first message should be the root cause of the problem whenever possible: users should not be forced to search a hundred messages to find the root cause. In this way, the procedure: * solve the first error * reconvert * solving the new first error * reconvert * etc. should always deterministically lead to a resolution of all problems. Error messages are normally sorted by file, line and column, regardless of which conversion stage they happened (e.g. a tokeniser error first gets reported before a parser error). There is however one important exception to that: broken cross references are always reported last. For example, consider the following syntactically wrong document: ``` = a \x[b] `` == b ``` Here we have an unterminated code block at line 5. However, this unterminated code block leads the header `b` not to be seen, and therefore the reference `\x[b]` on line 3 to fail. Therefore, if we sorted naively by line, the broken reference would shoe up first: `` error: tmp.bigb:3:3: cross reference to unknown id: "b" error: tmp.bigb:5:1: unterminated literal argument `` But in a big document, this case could lead to hundreds of undefined references to show up before the actual root unterminated literal problem.: `` error: tmp.bigb:3:3: cross reference to unknown id: "b" error: tmp.bigb:4:3: cross reference to unknown id: "b" error: tmp.bigb:5:3: cross reference to unknown id: "b" ... error: tmp.bigb:1000:1: unterminated literal argument `` Therefore, we force undefined references to show up last to prevent this common problem: `` error: tmp.bigb:1000:1: unterminated literal argument error: tmp.bigb:3:3: cross reference to unknown id: "b" error: tmp.bigb:4:3: cross reference to unknown id: "b" error: tmp.bigb:5:3: cross reference to unknown id: "b" ... `` = Security {parent=OurBigBook} = Arbitrary code execution {parent=Security} OurBigBook is designed to not allow arbitrary code execution by default on any command. This means that it it should be safe to just download any untrusted OurBigBook repository, and convert it with , even if you don't trust its author. In order to allow code execution for pre/post processing tasks e.g. from , use the <--unsafe-ace> option. Note however that you have to be careful in general, since e.g. a malicious author could create a package with their own malicious version of the `ourbigbook` executable, that you could unknowingly run with with the standard `npx ourbigbook` execution. = unsafe-xss {parent=Security} {title2=`--unsafe-xss`} OurBigBook HTML output is designed to be XSS safe by default, any non-XSS safe constructs must be enabled with a non-default flag or setting, see: . Of course, we are walking on eggs, and this is hard to assert, so the best thing to do later on will be to parse the output e.g. with https://developer.mozilla.org/en-US/docs/Web/API/DOMParser[`DOMParser`] to ensure that it is valid and does not contain any `script` tags, but it is not as simple as that: https://stackoverflow.com/questions/37435077/execute-javascript-for-xss-without-script-tags/61588322#61588322 XSS unsafe constructs lead to errors by default. XSS unsafe constructs can be allowed [from the command] line with: `` ./ourbigbook --unsafe-xss `` or from the file with an entry of form: `` "unsafe-xss": true `` = Contact {parent=OurBigBook} * https://github.com/ourbigbook/ourbigbook/issues for any public contact, see also: {full} * for private contact email: `admin@ourbigbook.com` = OurBigBook issue tracker {parent=Contact} https://github.com/ourbigbook/ourbigbook/issues = Developing OurBigBook {parent=OurBigBook} = Run OurBigBook master {parent=Developing OurBigBook} Install master globally on your machine: `` git clone https://github.com/ourbigbook/ourbigbook cd ourbigbook npm link npm link ourbigbook npm run build-assets `` so you can now run the `ourbigbook` command from any directory in your computer, for example to convert the ourbigbook documentation itself: `` ourbigbook . `` Note that this repository uses , and so the output will be present at `out/html/index.html` rather than `index.html`. We also have a shortcut for `npm link` and `npm link ourbigbook`: `` npm run link `` `npm run link` produces symlinks so that any changes made to the Git source tree will automatically be visible globally, see also: https://stackoverflow.com/questions/28440893/install-a-locally-developed-npm-package-globally The symlink structure looks like: `` /home/ciro/ourbigbook/node_modules/ourbigbook -> /home/ciro/.nvm/versions/node/v14.17.0/lib/node_modules/ourbigbook -> /home/ciro/ourbigbook `` As mentioned at , most users don't want global installations of OurBigBook. But this can be handy during development, as you can immediately see how your changes to OurBigBook source code affect your complex example of interest. For example, Ciro developed a lot of OurBigBook by hacking https://github.com/cirosantilli/cirosantilli.github.io directly with OurBigBook `master`. Just remember that if you add a new dependency, you must redo the symlinking business: `` npm install npm run link `` Asked if there is a better way at: https://stackoverflow.com/questions/59389027/how-to-interactively-test-the-executable-of-an-npm-node-js-package-during-develo[]. The symlink business can be undone with: `` npm unlink rm node_modules/ourbigbook `` = Run an isolated OurBigBook master {parent=Run OurBigBook master} mentions how to install and then run OurBigBook master globally, which is useful build some projects locally on master. To instead install locally in the current directory only instead, which can be useful for bisection: `` npm install ln -s .. node_modules/ourbigbook npm run build-assets `` You can now run tests as: `` npm test `` or the executable interactively as: `` ./ourbigbook . `` It also works from a subdirectory: `` mkdir -p tmp cd tmp ../ourbigbook . `` = Test system {parent=Developing OurBigBook} Run all tests: `` npm test `` To run all tests on PostgreSQL as in the , first setup the PostgreSQL database similarly to : `` createdb ourbigbook_cli psql -c "CREATE ROLE ourbigbook_user with login password 'a'" psql -c 'GRANT ALL PRIVILEGES ON DATABASE ourbigbook_cli TO ourbigbook_user' psql -c 'GRANT ALL ON SCHEMA public TO ourbigbook_user' psql -c 'GRANT USAGE ON SCHEMA public TO ourbigbook_user' psql -c 'ALTER DATABASE ourbigbook_cli OWNER TO ourbigbook_user' `` This got really annoying with PostgreSQL 15: https://stackoverflow.com/questions/67276391/why-am-i-getting-a-permission-denied-error-for-schema-public-on-pgadmin-4 And then run with: `` npm run test-pg `` List all tests: `` node node_modules/mocha-list-tests/mocha-list-tests.js main.js `` as per: https://stackoverflow.com/questions/41380137/list-all-mocha-tests-without-executing-them/58573986#58573986[]. Run just one test by name: `` npm test -- -g 'one paragraph' `` or on PostgreSQL: `` npm run test-pg -- -g 'one paragraph' `` As per: https://stackoverflow.com/questions/10832031/how-to-run-a-single-test-with-mocha todo: what if the test name is a substring? You will want these Bash aliases: `` npmtg() ( npm test -- -g "$*" ) npmtpg() ( npm run test-pg -- -g "$*" ) `` which allos you to just: `` npmtg one paragraph npmtpg one paragraph `` Run all tests that don't start with `cli:`: `` npm test -- -g '^(?!cli:)' `` This works because `-g` takes JavaScript regular expressions, so we can use negative lookahead, see also: https://stackoverflow.com/questions/26908288/with-mocha-how-do-i-run-all-tests-that-dont-have-slow-in-the-name = Inspect the database after a test {parent=Test system} Suppose you selected a single test: `` npm test -- -g 'cli: empty document' `` and want to inspect the database status. On SQLite it is not currently possible as tests run on a temporary in-memory database. TODO create a way. On PostgreSQL, you can just inspect the `ourbigbook_cli` table with the `psql` command line executable, e.g.. `` psql ourbigbook_cli -c 'select * from "Id"' `` That table is used to run each test, and will contain the contents of the last test executed. = Step debug when running a test {parent=Test system} Step debug during a test run. Add the statement: `` debugger; `` to where you want to break in the code, and then run: `` npm run testi -- -g 'p with id before' `` where `i` in `testi` stands for `inspect` from `node inspect`. Also consider the alias: `` npmtgi() ( npm run testi -- -g "$*" ) `` Note however that this does not work for tests that run the `ourbigbook` executable itself, since those spawn a separate process. TODO how to do it? Tried along: `` const out = child_process.spawnSync('node', ['inspect', 'ourbigbook'].concat(options.args), { cwd: tmpdir, input: options.stdin, stdio: 'inherit', }); `` but not working, related: https://stackoverflow.com/questions/23612087/gulp-target-to-debug-mocha-tests So for now, we are just printing the command being run as in: `` cmd: cd out/test/executable-ourbigbook.json-outputOutOfTree && ourbigbook --split-headers . `` so you can just re-run it manually with `node inspect` as in: `` cd out/test/executable-ourbigbook.json-outputoutoftree && node inspect "../../../ourbigbook" --split-headers . `` This works since the `tmp` directory is not deleted in case of failure. = `lib:` vs `cli:` tests {parent=Test system} There are two types of test in our test suite: * tests that call the `ourbigbook.convert` directly. These tests are prefixed with `lib: ` These tests don't actually create files in the filesystem, and just mock the filesystem instead with a dictionary. Database access is not mocked however, we just use Sqlite's fantastic in-memory mode. Whenever possible, these tests check their results just from the tree returned by the API, which is cleaner than parsing the HTML. But sometimes HTML parsing is inevitable. * tests that call the itself: * their titles are prefixed with `cli: ` * they tend to be a lot slower than the API test * can test functionality that is done outside of the `ourbigbook.convert` JavaScript API, notably stuff prevent in ourbigbook, so they are more end to end * don't do any mocking, and could therefore be more representative. However, as of 2022, we have basically eliminated all the hard database access mocking and are using the main database methods directly. So all that has to be mocked is basically stuff done in the ourbigbook executable itself. This means that except for more specific options, the key functionality of ourbigbook, which is to convert multiple paths, can be done very well in a non executable test. The only major difference is that instead of passing command line arguments like in `ourbigbook .` to convert multiple files in a directory, you have to use `convert_before` and `convert_before_norender` and specify conversion order one by one. This test robustness is new as of 2022, and many tests were previously written with executable that would now also work as unit tests, and we generally want that to be the case to make the tests go faster. * work by creating an actual physical filesystem under `out/test/` with the OurBigBook files and other files like `ourbigbook.json`, and then running the executable on that directory. `npm test` first deletes the `out/test` directory before running the tests. After running, the generated files are kept so you can inspect them to help debug any issues. * all these tests check their results by parsing the HTML and searching for elements, since here we don't have access to the . It wouldn't be impossible to obtain it however, as it is likely already JSON serializable. = Overview of files in this repository {parent=Developing OurBigBook} Source files: * \a[index.js]: main code. Must be able to run in the browser, so no Node.js specifics. Exposes the central `convert` function. You should normally use the packaged `_obb/ourbigbook.js` when using ourbigbook as an external dependency. * \a[ourbigbook]: CLI executable. Is basically just a CLI interface frontend to `convert` * \a[test.js]: contains all the Mocha tests, see also: * \a[README.md]: minimal Markdown README until GitHub / NPM support OurBigBook :-) * \a[ourbigbook_runtime.js]: * \a[main.scss] this file simply contains the customized CSS for https://docs.ourbigbook.com/[] and does not get otherwise distributed with OurBigBook, see: = Generated files {parent=Overview of files in this repository} = `dist` directory {parent=Generated files} `dist/` contains fully embedded packaged versions that work on browsers as per common JavaScript package naming convention. All the following files are generated with Webpack with: `` npm run webpack `` which is called from `npm run build-assets`. When publishing with , `dist` is placed under the <`_obb` directory>. The files in that directory are: * `dist/ourbigbook.js`: OurBigBook converter for browser usage. The source entry point for it is located at \a[index.js]. Contains the code of every single dependency used from `node_modules` used by `index.js`. This is notably used for the live-preview of a . * `dist/ourbigbook_runtime.js`: similar `dist/ourbigbook.js`, but contains the converted output of \a[ourbigbook_runtime.js]. You should include this in every OurBigBook HTML output. * `dist/ourbigbook.css`: minimized CSS needed to view OurBigBook output as intended. Embeds all OurBigBook CSS dependencies, notably the KaTeX CSS without which displays as garbage. The Sass entry point for it is: \a[ourbigbook.scss]. * `dist/editor.css`: the CSS of the editor, rendered from \a[editor.scss]. To develop these files, you absolutely want to use: `` npm run webpack-dev `` This runs Webpack in development mode, which has two huge advantages: * almost instantaneous compilation, as opposed to the unbearable 5 seconds+ of an optimized build * source maps are enabled, so you can see the fully: https://blog.jakoblind.no/debug-webpack-app-browser/ `npm run webpack-dev` also enables watch mode, so it keeps running until you turn it off. This setup also works seamlessly when [developing OurBigBook Web], just let the watch process run in a separate terminal. = `_obb` directory {parent=Generated files} When publishing with , certain files such as the <`dist` directory> are placed under the <`_obb` directory> on the final output. Being a , we can safely dump any autogenerated files under `_obb` without fear of name conflicts with other files. = The `out` directory {parent=Overview of files in this repository} OurBigBook stores some metadata and outputs it generates/needs inside the `./out/` directory that it creates inside the . Overview of files it contains: * `db.sqlite3`: * `publish`: a git clone of the source of the main repository to ensure that untracked files won't accidentally go into the output * `publish/out/db.sqlite3`: like `out/db.sqlite3` but from the clean clone of `out/publish` * `publish/out/publish`: the final generated output directory that gets published, e.g. as in = Conversion process overview {parent=Developing OurBigBook} A conversion follows the following steps done for each file to be converted: * tokenizer. Reads the input and converts it to a linear list of tokens. * parser. Reads the list of tokens and converts it into an . Parse can be called multiple times recursively when doing things like. * ast post process pass 1. An ast post process pass takes abstract syntax tree that comes out of a previous step, e.g. the original parser output, and modifies the it tree to achieve various different functionalities. We may need iterate the tree multiple times to achieve all desired effects, at the time of writing it was done twice. Each iteration is called pass. You can view snapshots of the tree after each pass with the <--log> option: `` ourbigbook --log=ast-pp-simple input.bigb `` This first pass basically does few but very wide reacing operations that will determine what data we will have to fetch from the database during the followng DB queries step. It might also do some operations that are required for pass 2 but that don't necessarily fetch data, not sure anymore. E.g. this is where the following functionality are implemented: * and * <\OurBigBookExample> and <--embed-includes>: they are stitched into the main AST * ast post process pass 2: we now do every other post process operation that was not done in pass 1, e.g.: * paragraphs, lists and tables * ast post process pass 3: this does some minimal tree hierarchy linking between parents and children. TODO could it be merged into 2? Feels likely * render, which converts our AST tree into a output string. This is run once for the toplevel, and once for every header of the document if are enabled. We need to do this because header renders are different from their toplevel counterparts, e.g. their first paragraph has id `p-1` and not `p-283`. All of those renders are done from the same parsed tree however, parsing happens only once. This step is skipped when using the <--no-render> option, or during . TODO it is intended that it should not be possible for there to be rendering errors once the previous steps have concluded successfully. This is currently not the case for at least one known scenario however: that are not defined. Sub-steps include: * DB queries: this is the first thing we do during the rendering step. Every single database query must be done at this point, in one go. Database queries are only done while rendering, never when parsing. The database is nothing but a cache for source file state, and this separation means that we can always cache input source state into the database during parsing without relying on the database itself, and thus preventing any circular dependencies from parsing to parsing.https://cirosantilli.com/china-dictatorship/reddit{ref} Keeping all queries together is fundamental for performance reasons, especially of in the : imagine doing 100 scattered server queries: `` SELECT * from Ids WHERE id = '0' SELECT * from Ids WHERE id = '1' ... SELECT * from Ids WHERE id = '100' `` vs grouping them together: `` SELECT * from Ids WHERE id IN ('0', '1', ..., '100') `` It also has the benefit of allowing us to remove `async`/`await` from almost every single function in the code, which considerably slows down the CPU-bound execution path. As an added bonus, it also allows us to clearly see the impact of database queries when using <--log perf>. We call this joining up of small queries into big ones "query bundling". * at the every end of the conversion, we then save the database changes calculated during parsing and post processing back to the DB so that the conversion of other files will pick them up. Just like for the SELECT, we do a single large INSERT/UPDATE query per database to reduce the round trips. Conversion of a directory with multiple input files works as follows: * do one pass without render * do a global database check/fixup for all files that have been parsed which checks in one go for: * check that all targets exist. When using the <\x magic argument>: * only one of the plural/singular needs to exist * we then decide which one to use and delete the other one. Both are initially placed in the database during the phase. * duplicate IDs * references from one non-header title to another non-header title as mentioned at <\x within title restrictions> Ideally, failure of any of the above checks should lead to the database not being updated with new values, but that is not the case as of writing. * do one conversion pass with render. To speed up conversion, we might at some point start storing a parsed JSON after the first conversion pass, and then just deserialize it and convert the deserialized output directly without re-parsing. The two pass approach is required to resolve = ID extraction {c} {parent=Conversion process overview} One of the main two passes done during conversion, where the files are parsed and all references stored in the database. = Abstract syntax tree {parent=Conversion process overview} = AST {c} {synonym} {title2} The implementation of much of the functionality of OurBigBook involves manipulating the abstract syntax tree. The structure of the AST is as follows: * `AstNode`: contains a map from argument names to the values of each argument, which are of type AstArgument * `AstArgument`: contains a list of `AstNode`. These are generally just joined up on the output, one after the other. One important exception to this are plaintext nodes. These nodes contain just raw strings instead of a list of arguments. They are usually the leaf nodes. We can easily observe the AST of an input document by using the <--log> following log options: `` ourbigbook --log=ast-simple input.bigb ourbigbook --log=ast input.bigb `` For example, the document: `` = My title {c} A link to \x[another-title]{c}{p} and more text. == Another title `` produces with `--log=ast-simple` the following output: `` ast Toplevel arg content ast H id="tmp" arg c arg level ast plaintext "1" arg numbered ast plaintext "0" arg scope ast plaintext "0" arg splitDefault ast plaintext "0" arg synonym ast plaintext "0" arg title ast plaintext "My title" ast P id="p-1" arg content ast plaintext "A link to " ast x arg c arg child ast plaintext "0" arg full ast plaintext "0" arg href ast plaintext "another-title" arg p arg parent ast plaintext "0" arg ref ast plaintext "0" ast plaintext " and more text." ast Toc id="toc" ast H id="another-title" arg c ast plaintext "0" arg level ast plaintext "2" arg numbered ast plaintext "0" arg scope ast plaintext "0" arg splitDefault ast plaintext "0" arg synonym ast plaintext "0" arg title ast plaintext "Another title" `` = Autogenerated tests {parent=Conversion process overview} The following scripts generate parametrized OurBigBook examples that can be used for performance or other types of interactive testing: * \a[generate-deep-tree]: `` ./generate-deep-tree 2 5 > deep_tree.tmp.bigb ./ourbigbook deep_tree.tmp.bigb `` Originally designed to be able to interactively play with a huge
to streamline JavaScript open close interaction. = generate-paragraphs {parent=Autogenerated tests} `` ./generate-paragraphs 10 > main.bigb `` Output: `` 0 1 2 3 4 5 6 7 8 9 `` = Pretty print HTML {parent=Developing OurBigBook} We have stopped making any effort to generate nicely indented HTML output as it just felt not worth it. Instead, if you want to debug some badly formatted HTML you can just use our pre-installed js-beautify dependency, e.g. with: `` npx js-beautify out/html/index.html `` = Performance {parent=Developing OurBigBook} To log some performance statistics, use: . = Speed comparison to other markup language implementations {parent=Performance} One quick and dirty option is to use `generate-paragraphs` which generates output compatible for most markup languages: `` ./generate-paragraphs 100000 > tmp.bigb `` On Ubuntu 20.04 https://cirosantilli.com/linux-kernel-module-cheat/#p51[Lenovo ThinkPad P51] for example: * OurBigBook 54ba49736323264a5c66aa5d419f8232b4ecf8d0 + 1, Node.js v12.18.1 `` time ./ourbigbook tmp.bigb `` outputs: `` real 0m5.104s user 0m6.323s sys 0m0.674s `` * Asciidoctor 2.0.10, Ruby 2.6.0p0: `` cp tmp.bigb tmp.adoc time asciidoctor tmp.adoc `` outputs: `` real 0m1.911s user 0m1.850s sys 0m0.060s `` * https://github.com/commonmark/cmark[cmark] 0.29.0: `` cp tmp.bigb tmp.md time cmark tmp.md > tmp.md.html `` outputs: `` real 0m0.091s user 0m0.070s sys 0m0.021s `` Holy cow, it is 200x faster than Asciidoctor! * https://github.com/markdown-it/markdown-it[markdown-it] at 5789a3fe9693aa3ef6aa882b0f57e0ea61efafc0 to get an idea of a JavaScript markdown implementation: `` time markdown-it tmp.md > tmp.md.html `` outputs: `` real 0m0.361s user 0m0.590s sys 0m0.060s `` * `cat` just to find the absolute floor: `` time cat tmp.bigb > tmp.tmp `` outputs: `` real 0m0.006s user 0m0.006s sys 0m0.000s `` = Performance log {parent=Performance} On P51: * `time ./ourbigbook --no-render . && time ./ourbigbook -S --log=perf README.bigb`: * ourbigbook 39e633f08b2abce10331b884c04d70dbe6d4565a before moving OurBigBook to Sequelize: 14s `` convert README.bigb perf start 248.0712810009718 perf tokenize_pre 248.36641899868846 perf tokenize_post 2027.6697090007365 perf parse_start 2028.678952999413 perf post_process_start 2684.3162699975073 perf post_process_end 5017.946601998061 perf split_render_pre 6572.925067000091 perf render_pre 5018.202895000577 perf render_2_pre undefined perf render_post 13093.658641997725 perf end 13126.138450000435 perf convert_input_end 14281.568749997765 perf convert_path_pre_sqlite 14281.64151499793 perf convert_path_pre_sqlite_transaction 14281.835940998048 perf convert_path_post_sqlite_transaction 14551.673818998039 perf convert_path_end 14551.860617998987 convert README.bigb finished in 14309.703324001282 ms perf convert_path_to_file_end 14552.230636000633 real 0m14.602s user 0m16.500s sys 0m1.832 `` `sqlite3 out/db.sqlite3 .schema` `` CREATE TABLE IF NOT EXISTS 'ids' ( id TEXT PRIMARY KEY, path TEXT, ast_json TEXT ); CREATE TABLE IF NOT EXISTS 'includes' ( from_id TEXT, from_path TEXT, to_id TEXT, type TINYINT ); CREATE INDEX includes_from_path ON includes(from_path); CREATE INDEX includes_from_id_type ON includes(from_id, type); CREATE TABLE IF NOT EXISTS 'files' ( path TEXT PRIMARY KEY, toplevel_id TEXT UNIQUE ); `` * ourbigbook 8e6a4311f7debd079721412e1ea5d647cc1c2941 after, OMG gotta debug perf now: `` real 0m29.595s user 0m34.095s sys 0m4.427s convert README.bigb perf start_convert undefined perf tokenize_pre 411.71094800531864 perf tokenize_post 2265.3646410033107 perf parse_start 2266.436312004924 perf post_process_start 2905.8304330036044 perf post_process_end 12113.761793002486 perf split_render_pre 16534.5258340016 perf render_pre 12114.092462003231 perf render_post 40937.611143000424 perf end_convert undefined perf convert_input_end 42042.85608199984 perf convert_path_pre_sqlite 42042.92515899986 perf convert_path_pre_sqlite_transaction 42147.847070001066 perf convert_path_post_sqlite_transaction 42732.242132000625 perf convert_path_end 42732.35991900414 convert README.bigb finished in 42327.62727500498 ms perf convert_path_to_file_end 42732.534088000655 real 0m42.779s user 0m46.530s sys 0m6.945s `` `sqlite3 out/db.sqlite3 .schema` `` CREATE TABLE `Files` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `path` TEXT NOT NULL UNIQUE, `toplevel_id` TEXT UNIQUE); CREATE TABLE sqlite_sequence(name,seq); CREATE INDEX `files_path` ON `Files` (`path`); CREATE INDEX `files_toplevel_id` ON `Files` (`toplevel_id`); CREATE TABLE `Ids` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `idid` TEXT NOT NULL UNIQUE, `path` TEXT NOT NULL, `ast_json` TEXT NOT NULL); CREATE INDEX `ids_path` ON `Ids` (`path`); CREATE TABLE `Refs` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `from_id` TEXT NOT NULL, `from_path` TEXT NOT NULL, `to_id` TEXT NOT NULL, `type` TINYINT NOT NULL); CREATE INDEX `refs_from_path` ON `Refs` (`from_path`); CREATE INDEX `refs_from_id_type` ON `Refs` (`from_id`, `type`); CREATE INDEX `refs_to_id_type` ON `Refs` (`to_id`, `type`); `` The question is: is it because we added `async` Everywhere, or is it because of changes in the database queries? Answering the question: added old DB at: https://github.com/ourbigbook/ourbigbook/tree/async-slow-old-db and it is fast again. So DB debugging it is, hurray. = Internals API {parent=Developing OurBigBook} Tokenized token stream and AST can be obtained as JSON from the API. Errors can be obtained as JSON from the API. Everything that you need to write OurBigBook tooling, is present in the main API. All tooling will be merged into one single repo. = The `\Toplevel` implicit macro {id=toplevel} {parent=Internals API} Every OurBigBook document is implicitly put inside a `\Toplevel` document and: * any optionally given arguments at the very beginning of the document will be treated as arguments of the `\Toplevel` macro * anything else will be put inside the <`content` argument> of the `\Toplevel` macro E.g., a OurBigBook document that contains: `` {title=My favorite title} And now, some content! `` is morally equivalent to: `` \Toplevel{title=My favorite title} [ And now, some content! ] `` In terms of HTML, the `\Toplevel` element corresponds to the ``, ``, `
` and `
` elements of a document. Trying to use the `\Toplevel` macro explicitly in a document leads to an error. = HTML document title {c} {parent=Internals API} * if the `title` argument of `toplevel` is given, use that * otherwise, if the document has a `\H[1]`, use the title of the first such header * otherwise use a dummy value = CSS {c} {parent=Developing OurBigBook} Our CSS is located at \a[main.scss] and gets processed through https://sass-lang.com[Sass]. To generate the CSS during development after any changes to that file, you must run: `` npm run sass `` which generates the final CSS file: `` main.css `` You then need to explicitly include that `main.css` file in your <--template>. For example, our \a[ourbigbook.liquid.html] contains a line: `` `` where `root_relpath` is explained under <--template>{full}. = `ourbigbook.common.scss` {c} {parent=CSS} The file `ourbigbook.common.scss` contains stand-alone Sass definitions that can be used by third parties. One use case is to factor out OurBigBook style with the site-specific boilerplate. E.g. a website that stores its custom rules under \a[main.scss] can do stuff like: `` @import 'ourbigbook/ourbigbook.common.scss'; `` = Mobile guidelines {parent=CSS} The main design goal on narrow screens is that there should never be horizontal scrolling enabled for the hole document, only on a per element basis. = Database guidelines {c} {parent=Developing OurBigBook} Every foreign key should have a manually created associated index, this is not done automatically by neither PostgreSQL nor Sequelize: * https://stackoverflow.com/questions/970562/postgres-and-indexes-on-foreign-keys-and-primary-keys * https://github.com/sequelize/sequelize/issues/5042 = Formal grammar {parent=Developing OurBigBook} TODO. Describe OurBigBook's formal grammar, and classify it in the grammar hierarchy and parsing complexity. = Release procedure {parent=Developing OurBigBook} = Do the release {parent=Release procedure} Before the first time you release, you need to login to NPM with: `` npm login `` Releases should always be made with the official https://www.npmjs.com/~ourbigbook-admin user. Then, every new release can be done automatically with the \a[release] script, e.g. to release a version 0.7.2: `` ./release 0.7.2 `` or to just increment the minor version, e.g. from the current `0.7.1` to `0.7.2` you could can omit the version argument: `` ./release `` That script does the following actions, aborting immediately if any of them fails: * runs [the tests] * publishes this documentation * updates `version` in `package.json` * creates a release commit and a git tag for it * pushes the source code * publishes the NPM package = Out-of-box testing {parent=Release procedure} After publishing, a good minimal sanity check is to ensure that you can render the template as mentioned in : `` cd ~ # Get rid of the global npm link development version just to make sure it is not being used. npm uninstall -g ourbigbook git clone https://github.com/ourbigbook/template cd template npm install npx ourbigbook . firefox out/html/index.html `` = Visual Studio Code extension release procedure {parent=Release procedure} `` npm install -g @vscode/vsce cd vscode vsce package vsce publish `` = OurBigBook media repository {parent=Developing OurBigBook} The repository https://cirosantilli.com/ourbigbook-media[] contains media for the project such as for documentation and It was created to keep blobs out of this repository. Some blobs were unfortunately added to this repository earlier on, but when we saw that we would need more and more, we made the sane call and forked that out. = Project governance {parent=Developing OurBigBook} The currently has a single top level executive, the , who has ultimate power over the project. There is currently no legal incorporated entity. These will likely change if the project ever gets any traction, but for now things are being ran in an informal manner only. = OurBigBook Admin {parent=Project governance} Toplevel executive of the , who has ultimate power over the project. OurBigBook.com account: https://ourbigbook.com/ourbigbook GitHub account: https://github.com/ourbigbook-admin = Publicity {parent=Developing OurBigBook} = Official accounts {parent=Publicity} * https://OurBigBook.com (case insensitive) * https://github.com/OurBigBook GitHub organization (case insensitive) * https://twitter.com/OurBigBook (case insensitive) * https://www.youtube.com/@OurBigBook (case insensitive) * LinkedIn company: https://www.linkedin.com/company/ourbigbook * LinkedIn group: https://www.linkedin.com/groups/9164882/ TODO vs the company. * Facebook: * page: https://www.facebook.com/OurBigBook (case insensitive) * group: https://www.facebook.com/groups/OurBigBook (case insensitive) * Discord: OurBigBook#6998 "OurBigBook's Server" invite link: https://discord.gg/A8P5zGcWUh * https://www.instagram.com/ourbigbook (case insensitive) = Merchandise {parent=Publicity} = Clothing {c} {parent=Merchandise} = T-shirt {c} {synonym} We are thinking about the following layout: * front: "OurBigBook.com" on upper left chest text * back: * "OurBigBook.com" on top across back. This positioning is crucial as it will show above chairs in amphitheatres * logo below text centered We are planning on using a clear green on white color scheme to reflect the current website CSS. TODO ideas: understand what students wear, and the copy it with our logo. E.g. for <#Oxbridge>, one could design <#college puffer jackets>[college puffer jackets]. = tshirtstudio.com {parent=Clothing} All items are available at: https://www.tshirtstudio.com/marketplace/ourbigbook-com from . Each sale includes a 5 dollar/euro/pound donation to the project. This is a reasonable website. It is a shame that you can't easily drag and drop move/resize images on the web UI, which has led us to do that manually on the in the source images. But still, relatively easy to use, and easy to setup a marketplace in. Another downside is that it does not seem possible to edit existing designs, so it is a bit hard to know exactly what you had done when it is time to update things. \Image[merch/tshirtstudio/tshirt-front.jpg] {title=TShirt Studio black t-shirt front} {description= Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-black-t-shirt[]. Very slightly too straight on shoulders, but not bad. The front color is a bit off/too white-ish, but not terrible. This is a picture from version one, which did not have the . Version one is no longer available for sale, only the new one with the slogan. } {height=800} {provider=github} \Image[merch/tshirtstudio/tshirt-back.jpg] {title=TShirt Studio black t-shirt back} {description=Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-black-t-shirt[].} {height=800} {provider=github} \Image[merch/tshirtstudio/hoodie-front.jpg] {title=TShirt Studio black hoodie front} {description= Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-black-zip-hoodie-2[]. Good quality, but the material is slightly warmer than I'd like, I tend to prefer slightly fluffier ones. This is a picture from version one, which did not have the . Version one is no longer available for sale, only the new one with the slogan. It was slighty concerning if the hoodie would cover the URL or not, but it does not do often in practice. } {height=800} {provider=github} \Image[merch/tshirtstudio/hoodie-back.jpg] {title=TShirt Studio black hoodie back} {description=Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-black-zip-hoodie-2[].} {height=800} {provider=github} \Image[https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-white-t-shirt-front.jpg] {title=TShirt Studio white t-shirt front} {description=Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-white-t-shirt[].} {height=600} \Image[https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-white-t-shirt-back.jpg] {title=TShirt Studio white t-shirt back} {description=Buy at: https://www.tshirtstudio.com/marketplace/ourbigbook-com/ourbigbook-com-white-t-shirt[].} {height=600} = Sticker {c} {parent=Merchandise} \Image[sticker.svg] {title=Sticker SVG} {border} {provider=github} {height=200} * https://www.redbubble.com/people/OurBigBook/shop (case insensitive) has a marketplace mechanism 6.64 pound/unit for the 21cm size, which is quite expensive. It is unclear how much they pay the creator. TODO: the following links are currently restricted because it is a new account: * https://www.redbubble.com/i/sticker/OurBigBook-com-sticker-with-URL-logo-and-slogan-by-OurBigBook/133297659.JCQM3 * https://www.redbubble.com/people/ourbigbook/works/133297659-ourbigbook-com-sticker-with-url-logo-and-slogan?asc=u They said would be unrestricted in five business days, but it was still not true after one month. It appears that you have to upload five designs for anything to be publicly available... that service is a bit crap. Have to find a new one later on. Their delivery is a bit slow, 7 business days in theory, but took at least 21 in reality. They must be streched thin. The product quality was good when it finally arrived though. \Image[merch/redbubble/21cm.jpg] {title=Redbubble 21cm sticker} {provider=github} {height=500} * https://stickerapp.co.uk/ does not seem to have a marketplace, 2 pounds/unit on an 11 unit order, so much cheaper. But why would we need 11 is the question. Just going with the marketplace for now. Standard delivery in a bout 7 business days. = Project identity {parent=Publicity} = Project logo {parent=Project identity} The logo can be seen at: . \Image[logo.svg] {height=150} {title=logo.svg} {description= Canonical project logo. This SVG file was actually manually created, and therefore counts as code and can be tracked on this git repository. Since it does not contain text, only geometric primitives, this SVG file does not rely on any external system fonts and is fully reproducible. } \Image[logo-256.png] {height=150} {title=logo-256.png} {provider=github} {description= 256x256 PNG version of , ideal for profile pictures that don't support SVG. Generated with: `` convert logo.svg -resize 256x logo-256.png `` } \Image[logo-transparent.svg] {height=150} {provider=github} {title=logo-transparent.svg} {description= This is a version of logo.svg with a transparent background instead of the hardcoded black background. It was useful e.g. for t-shirt merch, where the t-shirt background choices were not perfectly black, and the black square would be visible (and possibly glossy) otherwise, which would not be nice. } \Image[logo-transparent-with-text.svg] {height=300} {provider=github} {title=logo-transparent-with-text.svg} {description= This version of the logo was useful when designing project on . On that website, you can't easily resize images with drag and drop, so: * leaving some extra margin at the top would make the text more likely visible considering the hoodie * leaving some extra margin around allows us to make the image a bit less huge and imposing } \Image[logo-transparent-with-text-and-slogan-2000.png] {height=300} {provider=github} {title=logo-transparent-with-text-and-slogan-2000.png} {description=This is perhaps a superior alternative to for , as the could clarify further what the merchandise is all about.} \Image[logo-transparent-with-text-and-slogan-2000-2150.png] {height=300} {provider=github} {title=logo-transparent-with-text-and-slogan-2000-2150.png} {description= This is the same as `logo-transparent-with-text-and-slogan-2000.png` but with a 150 px border added to the top to ensure that the hoodie hood won't hide the URL. It was created with: `` convert logo-transparent-with-text-and-slogan-2000.png -gravity north -background transparent -splice 0x150 logo-transparent-with-text-and-slogan-2000-2150.png `` } Some rationale: * the lowercase `b` followed by uppercase `B` gives the idea of big and small * the small `o` looks a bit like a degree symbol, which feels sciency. It also contributes to the idea of small to big: `o` is smallest, `b` a bit larger, and `B` actually big * keep the same clear on black feeling as the default CSS output * yellow, green and blue are the colors of Brazil, where Ciro Santilli was born! It might be cool if we were able to come up with something that looks more like an actual book though instead of just using a boring lettermark. A good point of the current design is that it suggests a certain simplicity. We want the explanations of our website to be simple and accessible to all. = Text logo {parent=Project logo} In addition to the pictorial logo, we have also created a few textual logos which might be useful. We first designed them as a way to take up upper left chest square space nicely on T-shirts, as a long one line version of `ourbigbook.com` would be too small and unreadable. The main idea of the text logo is to make a letter square with uppercase monospace font letters: `` OUR BIG BOOK .COM `` Could make the `OBB` red and other letters white. But that does come a bit closer to our dreaded https://en.wikipedia.org/wiki/ÖBB[ÖBB] name competitor. Note that monospace fonts are not actually square, only fixed width: https://graphicdesign.stackexchange.com/questions/45260/name-for-type-that-has-the-same-width-and-height Another idea to differentiate from ÖBB would be to go lowercase: `` obb `` \Image[text-logo/3x3.svg] {title=3x4.svg text logo} {description=This one was done without scaling. The font is a slightly tall rectangle, leading to a natural 3x4 aspect ratio.} {provider=github} \Image[text-logo/3x3-1000.png] {title=3x4-1000.png text logo} {description=This is a rasterization of 3x4.png to 1000x1000 px. Since SVG does not contain the actual font, we always need PNG exports for reproducibility.} {provider=github} \Image[text-logo/3x3.svg] {title=3x3.svg text logo} {description=This was made by scaling down a version of the 3x4.svg logo. We had to add some extra space between lines before however, otherwise it would feel too cramped after scaling.} {provider=github} \Image[text-logo/3x3-1000.png] {title=3x3-1000.png text logo} {provider=github} \Image[text-logo/circle-1000.png] {title=circle-1000.png text logo} {description=Useful for circular profile pictures.} {provider=github} \Image[text-logo/square-1000.png] {title=square-1000.png text logo} {description=Useful for square profile pictures.} {provider=github} = Project slogan {parent=Project identity} We were thinking something like: \Q[Learn for real!] but we wonder if that wouldn't be too close to: https://www.learningforreal.org/[]. Maybe not. Another one that is also somewhat taken is: \Q[You be the teacher] https://www.teacherspayteachers.com/Product/You-Be-The-Teacher-Independent-Research-Project-Distance-Learning-3785062 = Project name {parent=Project identity} A free domain name was the key restriction. We almost went with `destroyuni.com`!!! But Ciro regained his senses in the end. A two word domain would be sweet though. But Ciro was very happy with OurBigBook. Some other `` domains: * https://www.mysmallcar.com = Project banner {parent=Project identity} \Image[banner-topics-signed-in-800.png] {title=Topics page banner} {description= Initial project banner showing the feature. Not very subtle, but will do as a placeholder. The downside of this is that much of its bottom left is hidden by the profile picture on websites such as Twitter and LinkedIn. The banner is also a bit narrow for certain websites, and either looks rescaled, or is outright not allowd with editing, e.g. YouTube requires a minium width of 1024, with 2048 recommended. YouTube is also extremelly picky and hard to make the banner look right as it reserves mandatory huge height for TV displays! The best approach we can find is to make the image huge and fill in black with: `` convert banner-topics-signed-in-800.png -background black -gravity center -extent 2000x1000 tmp.png `` and then drag the image selection so that the desktop view covers the area we care about. } {provider=github} Websites that accept banners: * Twitter * LinkedIn * YouTube * Reddit * Patreon * Facebook = Demo videos {parent=Publicity} Demo videos are uploaded to the [official YouTube account]: https://www.youtube.com/@OurBigBook The video files together with the assets used to make them are also made available in the under the https://github.com/ourbigbook/ourbigbook-media/tree/master/video[`video/` directory]. Video guidelines: * desktop recording area size: 720x720. This could perhaps be optimized, but this is a reasonable size that works both as an YouTube Short and Twitter post. Previously we had been using 700x700, but at some point YouTube appears to have stopped generating 720p resolution for those, and 480p is just too bad. We've been happily using vokoscreenNG. A good technique is to move the recording window to the lower left bottom of the screen, which stops things from floating around too much. * use Chromium/Chrome to record * resize window to fit recording area horizontally by using the Ctrl + Shift + C debugger view. Make sure to also resize the browser window vertically (cannot be done on debugger, needs resizing actual window) otherwise you won't be able to scroll if the page is not taller than the viewport. * be careful about single pixel black border lines straying in the recording area, they are mega visible against the clear chrome browser bar on the finished output! * music style guidelines: cool, beats, techno, mysterious, upbeat Some of the videos contain non-fully free YouTube music added via the YouTube UI. Reupload together with the video files appears however allowed. Ideally we should use fully https://ourbigbook.com/go/topic/cc-by-sa[CC BY-SA] music, but it is quite hard to find good ones. NC is not acceptable. * hardcode subtitles in the video. No voice. Previously we were using Aegisub to create the subtitles in `.ass` format and ffmpeg to hardcode: `` ffmpeg -i raw.mkv -vf subtitles=sub.ass out.mkv `` but later we https://www.youtube.com/watch?v=1yuc60lz2Us[learnt about KDenlive support for subtitles] and moved to that instead as it is even more convenient to have it all in one place. Use: * 22pt white font with black background to improve readability * aim to have 3/4 lines of subtitle maximum per frame When recording, make sure that all key mouse action happens on the top half of the viewport, otherwise it will get covered by the subtitles in downstream editing. * on YouTube, add the video as the first video of the "Videos" playlist: https://www.youtube.com/playlist?list=PLshTOzrBHLkZlpvTuBdphKLWwU7xBV6VF This list is needed because otherwise YouTube's stupid "Shorts" features produces two separate timelines by default, one for shorts and one for non-shorts. With this list, all videos can be seen easily as non-shorts. = OurBigBook.com Fellowship {parent=Publicity} The has sporadically offered a fellowship called the "OurBigBook.com Fellowship". Its recipients are called the "OurBigBook.com Fellows". The goal of the fellowship is to pay brilliant students to focus exclusively on pursuing ambitious goals in STEM research and education for a pre-determined length of time, without having to worry about earning money in the short term. The fellowship is both excellency and need based, focusing on brilliant students from developing countries whose families were not financially able to support them. Being brilliant, such students would be tempted and able to go for less ambitious jobs that pay them the short term. The goal of the fellowship is to free such students to instead pursue more ambitious, longer term goals. Or in other words: to allow smart people to https://www.youtube.com/watch?v=khOaAHK7efc[do whatever the fuck they really want to do]. The fellowship is paid as a single monetary transfer to the recipient. There are no legally binding terms to the fellowship: we pick good people and trust them to do what they think is best. The fellowship is more accurately simply a donation. There is no contract. Whatever happens, the OurBigBook Project will never able to take legal action against a recipient for not "using well" their donation. The following ethical guidelines are however highly encouraged: * to acknowledge the funding where appropriate, e.g.: * at "funding slide" (usually the last one) of a presentation for work done during, or that you feel is a direct consequence of the fellowship * by marking yourself as a "OurBigBook.com Fellow" on LinkedIn, under the organization: https://www.linkedin.com/company/ourbigbook for the period of award * keep in touch. Let us know about any large successes (or failures!) you've have as the consequence of the funding, e.g. publications, starting a cool new job, or deciding to quit academia. * give back culture: if one day, in a potentially far and undefined future, recipients achieve a stable financial situation with some money to spare, they are encouraged to give back to the OurBigBook.com Fellowship fund an amount at least equal to their funding. This enables us to keep sustainably investing in new brilliant talent who needs the money. We are more than happy to take the consider the fellow's suggestion for a recipient of their choice. Remember that an investment in the American stock market doubles every 10 years. So if you do go into a money making area, can you as a "person investment", match, or even beat the market? :-) Or conversely, the sooner you give back, the less you are morally required to give back. Fellows who go on to work on charitable causes, which includes the incredibly underpaid academics jobs, absolutely don't have to give back. If you are able to give back by doing a corresponding amount of good to the world all the better. It is you that have to look into your heart and decide: how much free or underpaid work have I done? And then if there is some money left after this consideration, you give that amount back. * pivoting is OK. If you decide half way that your initial project plan is crap, change! We can only notice that something won't work once we try to do it for real. At least now you know! If you do pivot to something that makes money immediately however, the correct thing to do is to return any unused funds of the fellowship. The sooner you pay, the lesser your moral dividend obligation, right? * be bold. Don't ever think "I'll take this safer option because it will allow me to pay back earlier". The entire goal of the scholarship is to allow smart people to take greater risks. If you took the risk, e.g. made a startup instead of going to a safer job, failed, and that made you make less money than you would have otherwise, no problem, deduce that cost from the value you can return in the future, and move on. But if you take a bet and it pays big time, do remember us ;-) We also encourage fellows to take good care of their health, and strive for a good work/life balance. Exercise. Eat well. Rest. Don't work when you're tired. Take time off if when you are stressed. Keep in touch with good friends and family. Talk to someone if you feel down. Taking good care of yourself pays back with great dividends in the long run. Invest in it. = OurBigBook.com Fellows {parent=OurBigBook.com Fellowship} {scope} This section lists current and past OurBigBook.com Fellows. It is a requirement of the fellowship that fellows should be publicly listed here. Publicly known updates on related to their fellowship projects may also be added here where appropriate, notably successes! But we also embrace failure. All must know that failure is a possibility, and does happen. If you can't fail, you're not dreaming big enough. Failing is not bad, it is inevitable. = 2022 {parent=OurBigBook.com Fellows} = Letícia Maria Paz De Lima {parent=2022} 2022-12: https://bv.fapesp.br/en/pesquisador/717847/leticia-maria-paz-de-lima[Letícia Maria Paz De Lima] is awarded 10,000 Brazilian Real to help her: \Q[Focus on her https://ourbigbook.com/go/topic/quantum-computing[quantum computing] studies and research until 2023-06-30 (end of her third year), with the future intention of pursuing a https://ourbigbook.com/cirosantilli/doctor-of-philosophy[PhD] abroad in that area.] At the time of award, Letícia was a 3rd year student at the https://ourbigbook.com/go/topic/molecular-sciences-course-of-the-university-of-sao-paulo[Molecular Sciences Course of the University of São Paulo] and held a https://fapesp.br/bolsas/ic[FAPESP Scientific Initiation Scholarship]. She had become interested in Quantum Computing in the past year, and is passionate about working on that promising area of technology. Her main mentors in the area have been https://scholar.google.com/citations?user=FbGL0BEAAAAJ&hl=it[professor Paulo Nussenzveig] and https://portal.if.usp.br/ifusp/pt-br/users/bamaral[Barbara Amaral] of the Institute of Physics of the https://ourbigbook.com/go/topic/university-of-sao-paulo[University of São Paulo].