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

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
+28,781 −37,753

Conversation

peterhoeg
Copy link
Member

@peterhoeg peterhoeg commented Oct 29, 2019 •
edited
Loading

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

@ofborg ofborg bot added 6.topic: emacs Text editor 6.topic: erlang 6.topic: GNOME GNOME desktop environment and its underlying platform 6.topic: golang 6.topic: nixos Issues or PRs affecting NixOS modules, or package usability issues specific to NixOS 6.topic: qt/kde 6.topic: ruby 6.topic: TeX Issues regarding texlive and TeX in general 6.topic: xfce The Xfce Desktop Environment 8.has: changelog 8.has: documentation This PR adds or changes documentation 8.has: module (update) This PR changes an existing module in `nixos/` labels Oct 29, 2019
@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. ;)

@ofborg ofborg bot added 6.topic: haskell 6.topic: python 6.topic: vim 2.status: merge conflict This PR has merge conflicts with the target branch labels Nov 5, 2019
@ofborg ofborg bot removed the 2.status: merge conflict This PR has merge conflicts with the target branch label 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
Reviewers

@nbp nbp

@thoughtpolice thoughtpolice

@WilliButz WilliButz

@FRidh FRidh

@infinisil infinisil

@jonringer jonringer

@peti peti

@ttuegel ttuegel

Assignees
No one assigned
Labels
6.topic: emacs Text editor 6.topic: erlang 6.topic: GNOME GNOME desktop environment and its underlying platform 6.topic: golang 6.topic: haskell 6.topic: nixos Issues or PRs affecting NixOS modules, or package usability issues specific to 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 This PR adds or changes documentation 8.has: module (update) This PR changes an existing module in `nixos/`
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