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.

Sign up for GitHub

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

Jump to bottom

doc/gnome: Port to Markdown #105284

Merged
merged 5 commits into from Dec 8, 2020
Merged

doc/gnome: Port to Markdown #105284

merged 5 commits into from Dec 8, 2020

Conversation

jtojnar
Copy link
Contributor

@jtojnar jtojnar commented Nov 28, 2020 •
edited

Closes: #104965

  • Changed variablelist entries to separate sections
  • Added anchors to list items inline using the span syntax.
  • Admonitions do not seem to work using the fenced div syntax (even though pandoc uses them in docbook→markdown conversion), will use docbook for now. Fixed in pandoc.

@jtojnar jtojnar closed this Nov 28, 2020
@jtojnar jtojnar reopened this Nov 28, 2020
@jtojnar jtojnar force-pushed the gnome-markdown branch 2 times, most recently from aaf60bd to 341e0ad Compare November 28, 2020 20:20
@ofborg ofborg bot added 6.topic: GNOME GNOME desktop environment and its underlying platform 8.has: documentation 10.rebuild-darwin: 0 10.rebuild-linux: 0 labels Nov 28, 2020
@jtojnar jtojnar force-pushed the gnome-markdown branch 2 times, most recently from c182bc4 to 7c052bf Compare December 1, 2020 05:57
@jtojnar jtojnar changed the base branch from staging to staging-next December 2, 2020 19:18
@jtojnar
Copy link
Contributor Author

jtojnar commented Dec 2, 2020

Rebased onto staging-next. Can be tested without rebuilding the world now.

@ryantm ryantm linked an issue Dec 3, 2020 that may be closed by this pull request
Convert Gnome from Docbook to CommonMark #104965
Closed
@ryantm ryantm mentioned this pull request Dec 5, 2020
Merged
10 tasks
@ryantm
Copy link
Member

ryantm commented Dec 5, 2020

I tried building the manual with this PR's changeset and it failed to apply all the patches:

builder for '/nix/store/h37h3kssv82np8h3r6a174awg0zb9s12-pandoc-2.11.2.drv' failed with exit code 1; last 10 log lines:
  applying patch /nix/store/mfxkx77s89zfyd9rhlggkqdmalzxjjc7-e516f89eead99054531d96832efa50e40cba48e5.patch
  patching file src/Text/Pandoc/Writers/Docbook.hs
  applying patch /nix/store/z71nh146w4yxzx5hdw8v5zaiqa6imwc1-340f7a6e538451f39bfa80116f3b907e018253e0.patch
  patching file src/Text/Pandoc/Writers/Docbook.hs
  applying patch /nix/store/hpjfc6jjm9v8hhhr6nhq0mprxkmqpidl-1ce1e61755bb6ebe57bebe8dadfa0448a2f31a63.patch
  patching file src/Text/Pandoc/Writers/Docbook.hs
  Hunk #1 succeeded at 44 with fuzz 2 (offset 4 lines).
  Hunk #2 succeeded at 95 (offset 4 lines).
  Hunk #3 FAILED at 177.
  1 out of 3 hunks FAILED -- saving rejects to file src/Text/Pandoc/Writers/Docbook.hs.rej

@jtojnar
Copy link
Contributor Author

jtojnar commented Dec 5, 2020

Yeah, the two pandoc patches change neighbouring regions and line-based patches cannot handle that. I have rebased the second one onto the first one now that jgm/pandoc#6923 has been merged.

jtojnar
jtojnar commented Dec 5, 2020
View reviewed changes
Copy link
Contributor Author

@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 diff of the generated HTML looks acceptable to me now. It entails the following:

  • Semantic literals have been replaced by non-specific backtick code element.
  • Inline anchors are now placed next to the span they are attached to, instead of adding id attribute to the span itself. I might open a pandoc PR to correct this but it works fine as is.
  • Anchors for paragraphs/list items are now inline anchors at their beginning, since Pandoc’s Markdown currently does not allow attaching ids to paragraphs or list items.
  • When building EPUB, there is the following warning Xref is only supported to listitems in an orderedlist: ssec-gnome-hooks-gdk-pixbuf.
  • The definition list has been replaced by headings as described above.

@jtojnar
Copy link
Contributor Author

jtojnar commented Dec 5, 2020

Actually, the EPUB seems to produce the following incorrect link <a class="xref" href="sec-language-gnome.html#ssec-gnome-hooks-gdk-pixbuf">???</a> but it has been like that even before the Markdown conversion.

@jtojnar
Copy link
Contributor Author

jtojnar commented Dec 5, 2020

Actually, it is not even limited to EPUB. Fixed that now as well.

@jtojnar jtojnar changed the base branch from staging-next to master December 7, 2020 22:49
@jtojnar
doc: rename gnome to section
e4c3cda
@jtojnar
pandoc: Add patches for nixpkgs docs
16dfe8d 
Until we update pandoc, these are necessary for faithful Markdown to Docbook conversion in the manual.
The following features are necessary for many pages, in particular the GNOME platform docs:

* Anchors should use `xml:id` attribute, as mandated by Docbook 5.
* Admonitions should be supported, including titles.

Additionally, xmlns should be set correctly for root element.
@jtojnar
doc: clean up makefile
64b8489 
The sectn and ulink hacks are not necessary since pandoc has been defaulting to Docbook 5 for a long time.
With the pandoc patches, we can get rid of id→xml:id replacement and xmlns hacks as well.
@jtojnar
doc: convert GNOME platform docs to markdown
be8a3b8
@jtojnar
doc/stdenv: Fix xref to gdk-pixbuf setup hook
6224887 
DocBook does not support creating labels for unordered list items so we need to add a link label ourselves.
ryantm
ryantm approved these changes Dec 8, 2020
View reviewed changes
Copy link
Member

@ryantm ryantm left a comment

Choose a reason for hiding this comment

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

Code, rendering, and diff with master manual all look good.

Adding patches to the regular pandoc derivation is kind of a bit of a departure from our regular policies, but those patches are in master, and we should be able to clean that up in a bit, and it seems nice if people want to do stuff with the manual to not have to know some special argument to pass, so I'm going to merge it.

@ryantm ryantm merged commit f81ad12 into NixOS:master Dec 8, 2020
@jtojnar jtojnar deleted the gnome-markdown branch December 8, 2020 05:27
@nixos-discourse
Copy link

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/happy-docsgiving/10214/23

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ryantm ryantm ryantm approved these changes

@worldofpeace worldofpeace Awaiting requested review from worldofpeace

Assignees
No one assigned
Labels
6.topic: GNOME GNOME desktop environment and its underlying platform 8.has: documentation 10.rebuild-darwin: 11-100 10.rebuild-linux: 101-500
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Convert Gnome from Docbook to CommonMark
3 participants
@jtojnar @ryantm @nixos-discourse