Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
org-readme tries to integrate a single lisp file library with a Readme.org file

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
el-get
melpa
Readme.org
dir
org-readme.el
org-readme.info

Readme.org

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
20121207.1718
Package-Requires
((http-post-simple “1.0”) (yaoddmuse “0.1.1”)(header2 “21.0”) (lib-requires “21.0”))
Last-Updated
Wed Aug 22 13:11:26 2012 (-0500)
By
Matthew L. Fidler
Update #
794
URL
https://github.com/mlf176f2/org-readme
Keywords
Header2, Readme.org, Emacswiki, Git
Compatibility
Tested with Emacs 24.1 on Windows.

Possible Dependencies

None

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.

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 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 recipie.
  • If you are using github, this library creates a el-get recipie.

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

Functions

Interactive Functions

org-readme-changelog-to-readme

(org-readme-changelog-to-readme)

This puts the emacs lisp change-log into the Readme.org file.

org-readme-convert-to-emacswiki

(org-readme-convert-to-emacswiki)

Converts Readme.org to oddmuse markup and uploads to emacswiki.

org-readme-convert-to-markdown

(org-readme-convert-to-markdown)

Converts Readme.org to markdown Readme.md.

org-readme-edit

(org-readme-edit)

Edit change comment for commit.

org-readme-edit-cancel

(org-readme-edit-cancel)

Cancel the edit log.

org-readme-edit-commit

(org-readme-edit-commit)

Changelog for editing.

org-readme-git

(org-readme-git)

Add The files to git.

org-readme-insert-variables

(org-readme-insert-variables)

Extracts variable documentation and places it in the Readme.org file.

org-readme-marmalade-post

(org-readme-marmalade-post)

Posts the current buffer to Marmalade.

org-readme-sync

(org-readme-sync &optional COMMENT-ADDED)

Syncs Readme.org with current buffer. When COMMENT-ADDED is non-nil, the comment has been added and the syncing should begin.

org-readme-to-commentary

(org-readme-to-commentary)

Change Readme.org to a Commentary section.

org-readme-top-header-to-readme

(org-readme-top-header-to-readme)

This puts the top header into the Readme.org file as Library Information

Internal Functions

org-readme-buffer-version

(org-readme-buffer-version)

Gets the version of the current buffer.

org-readme-build-el-get

(org-readme-build-el-get)

Builds an el-get recipe. This assumes github, though others could be added. Returns file name if created.

org-readme-build-melpa

(org-readme-build-melpa)

Builds a melpa recipe. This assumes github, though other could be added. Returns file name if created.

org-readme-find-readme

(org-readme-find-readme)

Find the Readme.org.

org-readme-get-change

(org-readme-get-change)

Get file for changelog commits.

org-readme-get-emacswiki-name

(org-readme-get-emacswiki-name)

Gets emacswiki-style name based on buffer.

org-readme-in-readme-org-p

(org-readme-in-readme-org-p)

Determine if the currently open buffer is the Readme.org

org-readme-insert-functions

(org-readme-insert-functions)

Extracts function documentation and places it in the Readme.org file.

org-readme-marmalade-version

(org-readme-marmalade-version PACKAGE)

Gets the marmalade version of the PACKAGE.

org-readme-remove-section

(org-readme-remove-section SECTION &optional TXT ANY-LEVEL AT-BEGINNING)

Remove org-mode SECTION. Optionally insert TXT. When ANY-LEVEL is non-nil, any level may be specified. When AT-BEGINNING is non-nil, if the section is not found, insert it at the beginning.

org-readme-single-lisp-p

(org-readme-single-lisp-p)

Determine if the Readme.org is in a directory with a single lisp file. If so, return the name of that lisp file, otherwise return nil.

org-readme-token

(org-readme-token)

Gets marmalade-token, if not already saved.

Variables

Customizable Variables

org-readme-add-changelog-to-readme

Add a Variables section to Readme.org

org-readme-add-functions-to-readme

Add a Functions section to Readme.org

org-readme-add-top-header-to-readme

Add Top Header information to Readme.org

org-readme-add-variables-to-readme

Add a Variables section to Readme.org

org-readme-build-el-get-recipe

Builds a el-get recipe based on github information

org-readme-build-info

Builds library-name.info from Reade.org using texi. Requires org-readme-build-texi to be non-nil, pandoc and makeinfo to be found. This will also create the directory entry using install-info, if it is found.

org-readme-build-markdown

Builds Readme.md from Readme.org

org-readme-build-melpa-recipe

Builds a melpa recipe based on github information

org-readme-build-texi

Builds library-name.texi from Readme.org, using Readme.md and pandoc. Requires org-readme-build-markdown to be non-nil as pandoc to be found.

org-readme-create-tar-package

Creates a tar package for use in ELPA

org-readme-default-template

Default template for blank Readme.org Files. LIB-NAME is replaced with the library.

org-readme-drop-markdown-after-build-texi

Removes Readme.md after texinfo is generated

org-readme-drop-texi-after-build-info

Removes the texi information after building info files.

org-readme-marmalade-server

Marmalade server website. This should start with http: and should notend with a trailing forward slash, just like the default value of http://marmalade-repo.org

org-readme-marmalade-token

Marmalade token to upload content to the marmalade server.

org-readme-marmalade-user-name

Marmalade user name to upload content to the marmalade server.

org-readme-remove-sections

List of sections to remove when changing the Readme.org to Commentary.

org-readme-remove-sections-from-markdown

List of sections to remove when changing the Readme.org to Markdown which is an intermediary for texinfo (using pandoc).

org-readme-sync-emacswiki

Posts library to the emacswiki. Requires yaoddmuse

org-readme-sync-git

Posts library to git

org-readme-sync-marmalade

Posts library to marmalade-repo.org

org-readme-use-melpa-versions

Use Melpa-type versions YYYYMMDD.HHMM instead of 0.0.0 versions

org-readme-use-pandoc-markdown

Uses pandoc’s grid tables instead of transferring the tables to html.

Internal Variables

org-readme-edit-mode-map

Keymap for editing change-logs.

Value: (keymap (24 keymap (19 . org-readme-edit-commit)) (3 keymap (11 . org-readme-edit-cancel) (3 . org-readme-edit-commit)) keymap (27 keymap (9 . ispell-complete-word)))

History

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 7-Aug-2012 Matthew L. Fidler Last-Updated: Tue Aug 7 19:14:34 2012 (-0500) #331 (Matthew L. Fidler) 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 7-Aug-2012 Matthew L. Fidler Last-Updated: Mon Aug 6 23:42:02 2012 (-0500) #328 (Matthew L. Fidler) 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)
Something went wrong with that request. Please try again.