From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thorsten Jolitz Subject: Re: Add-on: Github Flavored Markdown exporter Date: Tue, 08 Apr 2014 00:18:34 +0200 Message-ID: <87a9bwbx6t.fsf@gmail.com> References: Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:51507) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WXHr5-0002Om-6o for emacs-orgmode@gnu.org; Mon, 07 Apr 2014 18:17:32 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WXHr0-0007NS-C7 for emacs-orgmode@gnu.org; Mon, 07 Apr 2014 18:17:27 -0400 Received: from plane.gmane.org ([80.91.229.3]:59091) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WXHr0-0007NM-13 for emacs-orgmode@gnu.org; Mon, 07 Apr 2014 18:17:22 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1WXHqy-0005SH-5V for emacs-orgmode@gnu.org; Tue, 08 Apr 2014 00:17:20 +0200 Received: from g231111081.adsl.alicedsl.de ([92.231.111.81]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Tue, 08 Apr 2014 00:17:20 +0200 Received: from tjolitz by g231111081.adsl.alicedsl.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Tue, 08 Apr 2014 00:17:20 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Lars Tveito 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 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 Version: 1.0 URL: ## 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 ;; #+beginsrc emacs-lisp ;; (require 'outorg) ;; #+endsrc 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 (x8664-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
############################################################################## Is that the intended output? I did not try it on github ... -- cheers, Thorsten