Lars Tveito <larst...@student.matnat.uio.no> writes: > Hi! > > I have written an exporter for Github Flavored Markdown, which is a > derived back-end from the Markdown (vanilla) exporter. It adds > Github-style src-blocks, strike-through and table of contents. > > I think this could be useful because Org is a great tool for writing > README's. Org is supported by Github, but it currently does not support > syntax highlighting and table of contents (and has some other minor > quirks). > > Should I contribute this to the /lisp/contrib/? > > Best regards, > - Lars
This is nice, because I like to reuse the comment-sections of my elisp libraries as README files on github, but neither the raw org nor the markdown export looked so nice when I tried, so I used the ascii exporter. When I structure my .el files with outshine headers, with the whole comment section as one tree, I can simply use M-x outorg-edit-as-outorg on that entry and then export from the outorg-edit-buffer. I tried your library with outorg.el itself. Here is the comment section after converting it to outorg (the org-exporter does not like the reboxes, so I had to put manually , in front of them - is that a bug? Same problem with ascii-export): ####################################################################### * outorg.el --- Org-style comment editing Author: Thorsten Jolitz <tjolitz AT gmail DOT com> Version: 1.0 URL: https://github.com/tj64/outorg ** MetaData :PROPERTIES: :copyright: Thorsten Jolitz :copyright-years: 2013 :version: 1.0 :licence: GPL 2 or later (free software) :licence-url: http://www.gnu.org/licenses/ :part-of-emacs: no :author: Thorsten Jolitz :author_email: tjolitz AT gmail DOT com :inspiration: org-src :keywords: emacs org-mode comment-editing :END: ** Commentary *** About outorg [NOTE: For the sake of adding this library to MELPA, headlines had to be converted back from 'Org-mode style' to 'oldschool', and a few extra lines of required information had to be added on top of the MetaData section - just to comply with the required file formatting. All outshine, outorg and navi-mode functionality still works with this file. See my [[https://github.com/tj64/iorg][iOrg]] repository for examples of Emacs-Lisp and PicoLisp files structured 'the outshine way'.] `outorg' is like "reverse Org-Babel": editing of comment-sections from source code files in temporary Org-mode buffers instead of editing of Org-mode source-blocks in temporary source-code buffers. It should be used together with `outline-minor-mode' and `outshine.el'. Keep in mind, that `outorg' only works with outshine-style headlines like those produced by calling `comment-region' on Org-mode style headlines in a source-code buffer. Take this file as an example for suitable outline headlines in an Emacs Lisp buffer. In other major-modes, the `comment-start' character ';' of Emacs Lisp would be replaced by that of the respective major-mode, e.g. '#' in PicoLisp mode or '%' in LaTeX mode. `outorgs' main command is accessible via two different keybindings 1. with outline-minor-mode-prefix 'C-c' , ,--------------------------- , | C-c ' (outorg-edit-as-org) , `--------------------------- 2. with outline-minor-mode-prefix 'M-#' , ,--------------------------- , | M-# M-# (outorg-edit-as-org) , `--------------------------- used in source-code buffers where `outline-minor-mode' is activated with `outshine' extensions. The Org-mode edit-buffer popped up by this command has `outorg-edit-minor-mode' activated, a minor-mode with only 2 commands: ,,---------------------------------------- ,| M-# (outorg-copy-edits-and-exit) ,| C-x C-s (outorg-save-edits-to-tmp-file) ,`---------------------------------------- If you want to insert Org-mode source-code or example blocks in comment-sections, simply outcomment them in the outorg-edit buffer before calling `outorg-copy-edits-and-exit'. *** Installation Insert ;; #+begin_src emacs-lisp ;; (require 'outorg) ;; #+end_src in your .emacs. *** Bugs and Shortcomings `outorg' is line-based, it only works with 'one-line' comments, i.e. with comment-sections like those produced by `comment-region' (a command that comments or uncomments each line in the region). Those special multi-line comments found in many programming languages are not recognized and lead to undefined behaviour. *** Emacs Version `outorg.el' works with [GNU Emacs 24.2.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.6.4) of 2013-01-20 on eric]. No attempts of testing with older versions or other types of Emacs have been made (yet). ** ChangeLog | date | author(s) | version | |-----------------+-----------------+---------| | <2013-05-03 Fr> | Thorsten Jolitz | 1.0 | | <2013-02-11 Mo> | Thorsten Jolitz | 0.9 | ########################################################################## And here is the "*Org GFM Export*" buffer after exporting with your library: ########################################################################### - [outorg.el — Org-style comment editing](#outorg.el-—-org-style-comment-editing) - [MetaData](#metadata) - [Commentary](#commentary) - [About outorg](#about-outorg) - [Installation](#installation) - [Bugs and Shortcomings](#bugs-and-shortcomings) - [Emacs Version](#emacs-version) - [ChangeLog](#changelog) # outorg.el — Org-style comment editing Author: Thorsten Jolitz <tjolitz AT gmail DOT com> Version: 1.0 URL: <https://github.com/tj64/outorg> ## MetaData ## Commentary ### About outorg [NOTE: For the sake of adding this library to MELPA, headlines had to be converted back from 'Org-mode style' to 'oldschool', and a few extra lines of required information had to be added on top of the MetaData section - just to comply with the required file formatting. All outshine, outorg and navi-mode functionality still works with this file. See my [iOrg](https://github.com/tj64/iorg) repository for examples of Emacs-Lisp and PicoLisp files structured 'the outshine way'.] \`outorg' is like "reverse Org-Babel": editing of comment-sections from source code files in temporary Org-mode buffers instead of editing of Org-mode source-blocks in temporary source-code buffers. It should be used together with \`outline-minor-mode' and \`outshine.el'. Keep in mind, that \`outorg' only works with outshine-style headlines like those produced by calling \`comment-region' on Org-mode style headlines in a source-code buffer. Take this file as an example for suitable outline headlines in an Emacs Lisp buffer. In other major-modes, the \`comment-start' character ';' of Emacs Lisp would be replaced by that of the respective major-mode, e.g. '#' in PicoLisp mode or '%' in LaTeX mode. \`outorgs' main command is accessible via two different keybindings 1. with outline-minor-mode-prefix 'C-c' , ,————————— , | C-c ' (outorg-edit-as-org) , \`————————— 1. with outline-minor-mode-prefix 'M-#' , ,————————— , | M-# M-# (outorg-edit-as-org) , \`————————— used in source-code buffers where \`outline-minor-mode' is activated with \`outshine' extensions. The Org-mode edit-buffer popped up by this command has \`outorg-edit-minor-mode' activated, a minor-mode with only 2 commands: ,,-————————————— ,| M-# (outorg-copy-edits-and-exit) ,| C-x C-s (outorg-save-edits-to-tmp-file) ,\`-————————————— If you want to insert Org-mode source-code or example blocks in comment-sections, simply outcomment them in the outorg-edit buffer before calling \`outorg-copy-edits-and-exit'. ### Installation Insert ;; #+begin<sub>src</sub> emacs-lisp ;; (require 'outorg) ;; #+end<sub>src</sub> in your .emacs. ### Bugs and Shortcomings \`outorg' is line-based, it only works with 'one-line' comments, i.e. with comment-sections like those produced by \`comment-region' (a command that comments or uncomments each line in the region). Those special multi-line comments found in many programming languages are not recognized and lead to undefined behaviour. ### Emacs Version \`outorg.el' works with [GNU Emacs 24.2.1 (x86<sub>64</sub>-unknown-linux-gnu, GTK+ Version 3.6.4) of 2013-01-20 on eric]. No attempts of testing with older versions or other types of Emacs have been made (yet). ## ChangeLog <table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"> <colgroup> <col class="left" /> <col class="left" /> <col class="right" /> </colgroup> <thead> <tr> <th scope="col" class="left">date</th> <th scope="col" class="left">author(s)</th> <th scope="col" class="right">version</th> </tr> </thead> <tbody> <tr> <td class="left"><span class="timestamp-wrapper"><span class="timestamp"><2013-05-03 Fr></span></span></td> <td class="left">Thorsten Jolitz</td> <td class="right">1.0</td> </tr> <tr> <td class="left"><span class="timestamp-wrapper"><span class="timestamp"><2013-02-11 Mo></span></span></td> <td class="left">Thorsten Jolitz</td> <td class="right">0.9</td> </tr> </tbody> </table> ############################################################################## Is that the intended output? I did not try it on github ... -- cheers, Thorsten
