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

Jump to bottom

documentation: docbook to org [WIP] #72244

Closed
wants to merge 226 commits into from
Closed

documentation: docbook to org [WIP] #72244

wants to merge 226 commits into from

Conversation

peterhoeg
Copy link
Member

@peterhoeg peterhoeg commented Oct 29, 2019 •
edited

This isn't meant to merge but acts simply as a proof of concept for the conversion of existing documentation into org in relation to the ongoing discussion on documentation formats going forward.

cc: @danbst

This is how it was created:

#!/usr/bin/env nix-shell
#!nix-shell -i ruby -p git pandoc

def get_format(f)
  ext = File.extname f
  fmt = case ext
        when '.md'
          'commonmark'
        when '.xml'
          'docbook'
        else
          fail 'Unsupported file'
        end
  out = File.join(File.dirname(f), File.basename(f, ext) + '.org')

  return fmt, out
end

Dir.glob('**/*.{md,xml}').each do |f|
  fmt, out = get_format f
  `pandoc -r #{fmt} -w org -o #{out} #{f}`
  `git rm #{f}`
  `git add #{out}`
  `git commit -m '#{fmt} -> org'`
end

@nixos-discourse
Copy link

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

https://discourse.nixos.org/t/nixcon-2019-documentation-task-force-meeting-outcome/4551/10

@JohnAZoidberg
Copy link
Member

Does this result in a loss of information? Are there any attributes in the docbook XML, that org (or at least pandoc's conversion) cannot represent?

The scripts to build the documentation would also need to be updated. Do you have a version of the rendered docs as they are after this PR?

Should every file be committed on its own?

@danbst
Copy link
Contributor

danbst commented Oct 29, 2019

@JohnAZoidberg I think this is more a demonstration for what would automated "reformat-all-the-docs" PR look like.

@peterhoeg
Copy link
Member Author

I noticed a bunch of down-votes - the discussion about our documentation is taking place on discourse. This is very much just a POC and not something we should merge.

@chreekat
Copy link
Contributor

chreekat commented Nov 3, 2019

I noticed a bunch of down-votes - the discussion about our documentation is taking place on discourse. This is very much just a POC and not something we should merge.

Might want to make that more prominent in both the issue description and in the link from Discourse. ;)

@peterhoeg peterhoeg closed this Jan 13, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@nbp nbp Awaiting requested review from nbp

@thoughtpolice thoughtpolice Awaiting requested review from thoughtpolice thoughtpolice is a code owner

@WilliButz WilliButz Awaiting requested review from WilliButz

@FRidh FRidh Awaiting requested review from FRidh FRidh is a code owner

@infinisil infinisil Awaiting requested review from infinisil infinisil is a code owner

@jonringer jonringer Awaiting requested review from jonringer

@peti peti Awaiting requested review from peti

@ttuegel ttuegel Awaiting requested review from ttuegel ttuegel is a code owner

Assignees
No one assigned
Labels
6.topic: emacs 6.topic: erlang 6.topic: GNOME GNOME desktop environment and its underlying platform 6.topic: golang 6.topic: haskell 6.topic: nixos 6.topic: python 6.topic: qt/kde 6.topic: ruby 6.topic: TeX Issues regarding texlive and TeX in general 6.topic: vim 6.topic: xfce The Xfce Desktop Environment 8.has: changelog 8.has: documentation 8.has: module (update)
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@peterhoeg @nixos-discourse @JohnAZoidberg @danbst @chreekat