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

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

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

@nixos-discourse nixos-discourse commented Oct 29, 2019

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

@JohnAZoidberg JohnAZoidberg commented Oct 29, 2019

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 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

@peterhoeg peterhoeg commented Oct 30, 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.

@chreekat
Copy link
Contributor

@chreekat 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 force-pushed the peterhoeg:org branch from 3766dce to 8b004a5 Nov 5, 2019
@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
You can’t perform that action at this time.