Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DocBook -> CommonMark #106845

Merged
merged 5 commits into from Dec 17, 2020
Merged

DocBook -> CommonMark #106845

merged 5 commits into from Dec 17, 2020

Conversation

AndersonTorres
Copy link
Member

Motivation for this change
Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Ensured that relevant documentation is up to date
  • Fits CONTRIBUTING.md.

@AndersonTorres
Copy link
Member Author

AndersonTorres commented Dec 13, 2020

Marking these guys:

@ryantm

#105258
#105755
#105757
#105763
#105764

- `runCommandLocal` {#trivial-builder-runCommandLocal}
Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.

<note>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can use admonitions using fenced divs syntax.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something like that, @jtojnar ?

::: note
note written here
:::

@AndersonTorres
Copy link
Member Author

@jtojnar @ryantm done

@@ -0,0 +1,5 @@
# Locales {#sec-locales}
Copy link
Contributor

@jtojnar jtojnar Dec 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently, the old id was just locales.


Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.

::: {#special .note}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be indented, or it will be considered code in markdown.


Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.

::: {#special .note}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also why are you adding special anchor?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just followed the tutorial.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In Markdown extensions, attribute #foo is synonymous to id=foo and .bar means class=bar (probably originates from CSS).

For note admonition, you will want note class so that is

::: {.note}
foo
:::

When there is only a single class, pandoc allows to use shorter

::: note
foo
:::

That is equivalent and probably preferred.


Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build.

::: {note}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The period is important when using the brackets variant since .note is syntactic sugar for class=note.

Copy link
Contributor

@jtojnar jtojnar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The output looks good, both visually and diff from previous HTML.

@jtojnar jtojnar merged commit 5fb6fbc into NixOS:master Dec 17, 2020
@jtojnar
Copy link
Contributor

jtojnar commented Dec 17, 2020

Thanks.

@AndersonTorres
Copy link
Member Author

Phew! :)

@AndersonTorres AndersonTorres deleted the wip-documentation branch December 17, 2020 17:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants