Org Readme

Library Information

org-readme.el — Integrates Readme.org and Commentary/Change-logs.

Filename

org-readme.el

Description

Integrate Readme.org and Commentary/Change Logs.

Author

Matthew L. Fidler

Maintainer

Matthew L. Fidler

Created

Fri Aug 3 22:33:41 2012 (-0500)

Version

20151130.1948

Package-Requires

((http-post-simple “1.0”) (yaoddmuse “0.1.1”)(header2 “21.0”) (lib-requires “21.0”))

Last-Updated

Mon Nov 30 19:47:56 2015

By

Joe Bloggs

Update #

808

URL

https://github.com/mlf176f2/org-readme

Keywords

Header2, Readme.org, Emacswiki, Git

Compatibility

Tested with Emacs 24.1 on Windows.

Possible Dependencies

yaoddmuse http-post-simple org-html auto-document

Using org-readme

Org readme is used to:

• Create/Update a “History” section in the Readme.org based on the changelog section of the Emacs Log.
• Create/Update a “Library Information” Section Based on the Emacs lisp header.
• Create/Update a “Possible Dependencies” Section Based on the Emacs lisp header.
• Create/Update a “Functions” Section based on the functions defined in the single lisp library.
• Create/Update a “Variables” Section based on the variables defined in the single lisp library.
• Create/Update “Commands & keybindings” & “Customizable Options” sections as output by auto-document

All other sections of the Readme.org are then put into the “Commentary” section of the readme.org.

In addition this library defines org-readme-sync, a convenience function that:

• Asks for a commentary about the library change.
  • To exit/save press C-c C-c
• Asks the user whether to add ###;;;autoload magic cookies to the elisp file.
• Updates the headers in the elisp library according to the current date, time and the value of org-readme-author-name
• Asks if this is a minor revision
  • If it is a minor revision, bumps the revision up so the new library will be posted to marmalade-repo.org
  • The package will attempt to add the readme to the info documentation system within emacs.
• Syncs the Readme.org with the lisp file as described above.
• Updates emacswiki with the library description and the library itself (requires yaoddmuse).
• Updates Marmalade-repo if the library version is different than the version in the server (requires http-post-simple).
• Updates the git repository with the differences that you posted.
• If you are using github, this library creates a melpa recipe.
• If you are using github, this library creates a el-get recipe.

When org-readme-sync is called in a Readme.org file that is not a single lisp file, the function exports the readme in EmacsWiki format and posts it to the EmacsWiki.

EmacsWiki Page Names

EmacsWiki Page names are generated from the file. org-readme.el would generate a page of OrgReadme.

Why each required library is needed

There are a few required libraries. This is a list of the require libraries and why they are needed.

Library	Why it is needed
yaoddmuse	Publish to emacswiki
http-post-simple	Publish to marmalade-repo.org
header2	To create header and changelog
lib-requires	To generate the library dependencies
auto-document	To generate list of commands & options within elisp file (optional)

Notes

If you use auto-insert you may need to change your elisp entry of auto-insert-alist so that the end of the header section matches org-readme-end-section-regexp

Commands & keybindings

Below is a complete list of commands:

• org-readme-add-autoloads : Query user to add ###autoload magic comments to each function/macro/option.
  Keybinding: M-x org-readme-add-autoloads
• org-readme-insert-autodoc : Use - auto-document : to document functions and options in current elisp file.
  Keybinding: M-x org-readme-insert-autodoc
• org-readme-insert-variables : Extracts variable documentation and places it in the readme file.
  Keybinding: M-x org-readme-insert-variables
• org-readme-marmalade-post : Posts the current buffer to Marmalade.
  Keybinding: M-x org-readme-marmalade-post
• org-readme-edit-commit : Changelog for editing.
  Keybinding: C-x C-s
• org-readme-edit-cancel : Cancel the edit log.
  Keybinding: C-c C-k
• org-readme-edit : Edit change comment for commit.
  Keybinding: M-x org-readme-edit
• org-readme-convert-to-markdown : Convert Readme.org to markdown Readme.md.
  Keybinding: M-x org-readme-convert-to-markdown
• org-readme-convert-to-emacswiki : Converts Readme.org to oddmuse markup and uploads to emacswiki.
  Keybinding: M-x org-readme-convert-to-emacswiki
• org-readme-git : Add current file and other relevant files to git.
  Keybinding: M-x org-readme-git
• org-readme-gen-info : With the proper tools, generate an info and dir from the current readme.org.
  Keybinding: M-x org-readme-gen-info
• org-readme-sync : Syncs Readme.org with current buffer.
  Keybinding: M-x org-readme-sync
• org-readme-to-commentary : Replace Commentary section in elisp file with text from Readme.org.
  Keybinding: M-x org-readme-to-commentary
• org-readme-top-header-to-readme : Copy top header from the elisp file into the readme file as Library Information.
  Keybinding: M-x org-readme-top-header-to-readme
• org-readme-changelog-to-readme : This puts the Emacs Lisp change-log into the Readme.org file.
  Keybinding: M-x org-readme-changelog-to-readme
• org-readme-update-required-features-section : Update the required features section of the elisp file.
  Keybinding: M-x org-readme-update-required-features-section

Customizable Options

Below is a list of customizable options:

• org-readme-default-template : Default template for blank Readme.org Files. LIB-NAME is replaced with the library.
  default value: \n* Installation\n\nTo use without using a package manager:\n\n - Put the library in a directory in the emacs load path, like ~/.emacs.d\n - Add (require 'LIB-NAME) in your ~/.emacs file\n - If you have [[http://www.marmalade-repo.org/][marmalade-repo.org]], this LIB-NAME is part of the emacs packges you can install. Just type M-x package-install LIB-NAME marmalade \n\nThis is in emacswiki, so this package can also be installed using el-get.\n\nAfter installing el-get, Type M-x el-get-install LIB-NAME.\n
• org-readme-end-section-regexp : Regexp to match the end of a header/comments/changelog section in the elisp file comments.
  default value: ^+[ ]*$
• org-readme-features-regexp : Regexp to match the header line for the required libraries section.
  default value: ^[ ]*Features that might be required by this library:?[ ]*$
• org-readme-changelog-lines-regexp : Regexp matching changelog lines in the elisp file (you probably shouldn’t change this).
  default value: ^[ ]*\\([0-9][0-9]?-[A-Za-z][A-Za-z][A-Za-z]-[0-9][0-9][0-9][0-9]\\)[ ]*.*\n.*(\\([^)]*\\))[ ]*\n\\(\\(?:\n\\|.\\)*?\\)\n[ ]*\\([0-9][0-9]?\\)
• org-readme-final-changelog-line-regexp : Regexp matching the final changelog line in the elisp file (you probably shouldn’t change this).
  default value: \\([0-9][0-9]?-[A-Za-z][A-Za-z][A-Za-z]-[0-9][0-9][0-9][0-9]\\)[ ]*\\(.*\\)\n.*\n\\(\\(?:\n\\|.\\)*\\)
• org-readme-use-melpa-versions : Use Melpa-type versions YYYYMMDD.HHMM instead of 0.0.0 versions.
  default value: (quote prompt)
• org-readme-create-tar-package : Create a tar package for use in ELPA.
  default value: (quote prompt)
• org-readme-marmalade-server : Marmalade server website.
  default value: http://marmalade-repo.org
• org-readme-marmalade-token : Marmalade token to upload content to the marmalade server.
  default value: nil
• org-readme-marmalade-user-name : Marmalade user name to upload content to the marmalade server.
  default value: nil
• org-readme-author-name : Name to use as author when updating “Last-Updated” info in elisp header.
  default value: user-full-name
• org-readme-sync-emacswiki : Post library to the emacswiki.
  default value: (quote prompt)
• org-readme-sync-marmalade : Post library to marmalade-repo.org.
  default value: (quote prompt)
• org-readme-sync-git : Post library to git.
  default value: (quote prompt)
• org-readme-build-melpa-recipe : Build a melpa recipe based on github information.
  default value: (quote prompt)
• org-readme-build-el-get-recipe : Build an el-get recipe based on github information.
  default value: (quote prompt)
• org-readme-use-pandoc-markdown : Use pandoc’s grid tables instead of transferring the tables to html.
  default value: (quote prompt)
• org-readme-drop-markdown-after-build-texi : Remove Readme.md after texinfo is generated.
  default value: t
• org-readme-build-info : Build .info file from Reade.org using texi.
  default value: nil
• org-readme-drop-texi-after-build-info : Remove the texi information after building info files.
  default value: t
• org-readme-add-readme-to-lisp-file : Update elisp file header with commentary section of Readme.org.
  default value: (quote prompt)
• org-readme-use-autodoc : Use - auto-document : to document elisp file.
  default value: (quote prompt)
• org-readme-add-autodoc-to-readme : Copy - auto-document : output to Readme.org.
  default value: (quote prompt)
• org-readme-add-functions-to-readme : Add a Functions section to Readme.org.
  default value: (quote prompt)
• org-readme-add-variables-to-readme : Add a Variables section to Readme.org.
  default value: (quote prompt)
• org-readme-update-changelog : Add/update Changelog file.
  default value: (quote prompt)
• org-readme-add-changelog-to-readme : Add Changelog information to Readme.org.
  default value: (quote prompt)
• org-readme-add-top-header-to-readme : Add Top Header information to Readme.org.
  default value: (quote prompt)
• org-readme-remove-sections : List of sections to remove when changing the Readme.org to Commentary.
  default value: (quote ("History" "Possible Dependencies" "Library Information" "Installation" "Functions & macros" ...))
• org-readme-remove-sections-from-markdown : List of sections to remove when changing the Readme.org to
  default value: (quote ("Functions & macros" "Variables"))

History

30-Nov-2015

Add melpa recipe to package-build-recipes-dir (Joe Bloggs)

19-Nov-2015

Automatically update required features section in elisp comments (Joe Bloggs)

14-Nov-2015

Add auto-document integration (Joe Bloggs)

14-Nov-2015

Update “Last-Updated:”, “By:” & “Update #:” fields (Joe Bloggs)

12-Nov-2015

Refactor and tidy up code (Joe Bloggs)

8-May-2013

Add bugfix from vapniks for org-readme-to-commentary (Matthew L. Fidler)

3-May-2013

Uploading using org-readme. (Matthew L. Fidler)

22-Mar-2013

Bug fix for org-readme generating texinfo documentation from org-files. (Matthew L. Fidler)

22-Mar-2013

Separated out the texinfo conversion so that this may be applied to a generalized readme. (Matthew L. Fidler)

13-Mar-2013

Added bug fix so that starred initial variables do not mess with org-cut-region. That way, strange duplication of lines and regions do not occur. (Matthew L. Fidler)

10-Dec-2012

Changed melpa versions to be nil. However if a melpa version is detected, continue using it. (Matthew L. Fidler)

07-Dec-2012

Post to marmalade (Matthew L. Fidler)

07-Dec-2012

Remove tar support because it is broken without gnu tar. Gnu tar in windows is broken in opening elpa tarballs. (Matthew L. Fidler)

07-Dec-2012

Use 7zip to create tar. May create a readable tar for package.el (Matthew L. Fidler)

07-Dec-2012

Trying to test the org-readme tar balls (Matthew L. Fidler)

07-Dec-2012

Trying to post the tar package again. (Matthew L. Fidler)

07-Dec-2012

Bug fix – Tar package contents to include trailing /, otherwise emacs complains :( (Matthew L. Fidler)

07-Dec-2012

Bug fix for MELPA versions. (Matthew L. Fidler)

07-Dec-2012

Updated org-readme to use MELPA versions. Therefore when you upload to marmalade-repo and MELPA doesn’t pick up your revision, you can download the latest version yourself and try it out. (Matthew L. Fidler)

07-Dec-2012

Added info to melpa recipie. (Matthew L. Fidler)

07-Dec-2012

Attempted to add Readme in info format in the elpa package. (Matthew L. Fidler)

07-Dec-2012

Bug fix for deleting directory. (Matthew L. Fidler)

07-Dec-2012

Remove the directory that was created to make the package tarball (Matthew L. Fidler)

07-Dec-2012

Attempted to fix the package information file. (Matthew L. Fidler)

07-Dec-2012

Added tar package that includes the info file (Matthew L. Fidler)

07-Dec-2012

No longer deletes ilg files. (Matthew L. Fidler)

07-Dec-2012

Bug fix for info generation. (Matthew L. Fidler)

07-Dec-2012

Added mecahism to build info files and dir files for elpa package. (Matthew L. Fidler)

07-Dec-2012

Get description from info file. (Matthew L. Fidler)

07-Dec-2012

The description should now be picked up. (Matthew L. Fidler)

07-Dec-2012

Attempting to update description. (Matthew L. Fidler)

07-Dec-2012

Test directory entry (Matthew L. Fidler)

07-Dec-2012

Added directory entry to texinfo file. (Matthew L. Fidler)

18-Sep-2012

Bug fix to allow changes that read (Matthew L. Fidler)

12-Sep-2012

Handle errors with the package gracefully. to include the author name who updated the file. (Matthew L. Fidler)

12-Sep-2012

Handle errors with the package gracefully. (Matthew L. Fidler)

12-Sep-2012

Bug fix to eliminate duplicate headers in Readme.org and emacswiki (Matthew L. Fidler)

12-Sep-2012

Bug fix when org todo faces are not set. (Matthew L. Fidler)

12-Sep-2012

Added bug fix when org-todo-keyword-faces is undefined. (Matthew L. Fidler)

22-Aug-2012

Attempting to upload again (Matthew L. Fidler)

22-Aug-2012

Now will remove variable name and functions from markdown and outputted texinfo. (Matthew L. Fidler)

21-Aug-2012

Bug fix. When variables/functions are documented with an initial asterisk, change that asterisk to a bulleted item. (Matthew L. Fidler)

21-Aug-2012

Another documentation update where I document how to change the comment and that org-readme may change the minor revision of the library. (Matthew L. Fidler)

21-Aug-2012

Updated the documentation for org-readme. (Matthew L. Fidler)

20-Aug-2012

Bug fix for variables that don’t really transport well to the documentation. (Matthew L. Fidler)

20-Aug-2012

Bump minor version for marmalade-repo.org (Matthew L. Fidler)

20-Aug-2012

Attempt to fix the History list (Matthew L. Fidler)

20-Aug-2012

Added ability to customize which sections are added to the Readme.org (Matthew L. Fidler)

20-Aug-2012

Bug fix for creating function readme (Matthew L. Fidler)

20-Aug-2012

Will now remove the Functions and Variables sections before putting them in the commentary section. (Matthew L. Fidler)

20-Aug-2012

Attempt to remove Readme.md when not needed. (Matthew L. Fidler)

20-Aug-2012

Added ability to add function documentation and variable documentation to the Readme.org file (Matthew L. Fidler)

20-Aug-2012

Added pandoc markdown table support (optional) (Matthew L. Fidler)

13-Aug-2012

Another attempt to make texinfo documents. (Matthew L. Fidler)

13-Aug-2012

Added texinfo output. Allows native emacs documentation. (Matthew L. Fidler)

13-Aug-2012

Tried to post behind firewall. Reattempting. (Matthew L. Fidler)

13-Aug-2012

Changed the org-readme-remove-section to use org-cut-subtree. Hopefully all errors will resolve themselves now. (Matthew L. Fidler)

11-Aug-2012

Reverted. Still buggy. (Matthew L. Fidler)

11-Aug-2012

Another attempt at bug fix to remove section. (Matthew L. Fidler)

11-Aug-2012

Another attempt at a remove-section fix. (Matthew L. Fidler)

11-Aug-2012

Bug fix for org-readme version tagging. (Matthew L. Fidler)

11-Aug-2012

Test the bug where some of the section text is deleted (Matthew L. Fidler)

11-Aug-2012

Added more documentation (Matthew L. Fidler)

11-Aug-2012

One last bug fix to the markdown export engine. (Matthew L. Fidler)

11-Aug-2012

Markdown bug fix (Matthew L. Fidler)

11-Aug-2012

Bug fix for el-get recipe. (Matthew L. Fidler)

11-Aug-2012

Added the ability to create a markdown Readme (Readme.md) as well as adding a el-get recipe. (Matthew L. Fidler)

11-Aug-2012

Bug fix for emacswiki post and melpa bug fix (Matthew L. Fidler)

11-Aug-2012

Bug fix for adding melpa recipes. (Matthew L. Fidler)

11-Aug-2012

Bug fix for creating melpa recipe. (Matthew L. Fidler)

11-Aug-2012

Added ability to add melpa recipe (Matthew L. Fidler)

11-Aug-2012

Bug fix for pushing tags to a git repository (Matthew L. Fidler)

11-Aug-2012

Another fix for git tags. (Matthew L. Fidler)

11-Aug-2012

Found a bug, let see if tagging works now. (Matthew L. Fidler)

11-Aug-2012

Added Git tagging of new versions. Lets see if it works. (Matthew L. Fidler)

11-Aug-2012

Git push worked. Bumping minor version. (Matthew L. Fidler)

11-Aug-2012

Attempted to push repository again. (Matthew L. Fidler)

11-Aug-2012

Attempt to push with git. Something changed. (Matthew L. Fidler)

11-Aug-2012

Added better Package-Requires tag. (Matthew L. Fidler)

11-Aug-2012

Made request for minor revision earlier, and fixed bug. (Matthew L. Fidler)

11-Aug-2012

Fixed code typo (Matthew L. Fidler)

11-Aug-2012

Bug fix for deleting a section of a Readme.org file. (Matthew L. Fidler)

11-Aug-2012

Testing bug. (Matthew L. Fidler)

11-Aug-2012

Minor bug fix. (Matthew L. Fidler)

11-Aug-2012

Bug fix for comment sync, now Readme.org file is translated to lisp file. Additionally, asks for version bump. (Matthew L. Fidler)

11-Aug-2012

Bug fix for syncing readme. Now the returns should not be as prevalent. (Matthew L. Fidler)

11-Aug-2012

Attempting to post to marmlade again… (Matthew L. Fidler)

11-Aug-2012

Attempting to fix org-readme-marmalade-post. (Matthew L. Fidler)

11-Aug-2012

Bug fix to upload to emacswiki and upload to marmalade-repo (Matthew L. Fidler)

11-Aug-2012

Added marmalade-repo support. Now org-readme should upload to marmalade-repo when the version is different from the latest version. (Matthew L. Fidler)

08-Aug-2012

Fixed preformatting tags in emacswiki post. Previously they may have been replaced with <PRE></pre> instead of <pre></pre>. This makes the emacswiki page display correctly. (Matthew L. Fidler)

07-Aug-2012

To use, put (require ‘ess-smart-underscore) in your ~/.emacs file (Matthew L. Fidler)

7-Aug-2012

Added a Comment to EmcsWiki pages that states that the content of the page will likely be overwitten since it is automatically generated by org-readme (Matthew L. Fidler)

7-Aug-2012

Added more documentation. (Matthew L. Fidler)

06-Aug-2012

Added support for uploading Readme.org files to emacswiki without having to have a single associated lisp file. (Matthew L. Fidler)

06-Aug-2012

Bug fix for syncing from the single lisp file. (Matthew L. Fidler)

06-Aug-2012

Added the ability to call org-readme-sync from Readme.org (Matthew L. Fidler)

05-Aug-2012

Added git pushing to org-readme (Matthew L. Fidler)

05-Aug-2012

Added git support as well as a comment mode. The only thing that should need to be called is org-readme-sync (Matthew L. Fidler)

04-Aug-2012

Added syncing with emacswiki. (Matthew L. Fidler)

04-Aug-2012

Initial Release (Matthew L. Fidler)