Re: [Emacs-orgmode] Adapting org-mode to my needs

[Carsten Dominik]

Hi David,


On Apr 18, 2006, at 17:06, David O'Toole wrote:

> This email is about that other 2 percent :-) as I would like to adapt
> Org-mode to my needs.

If this is 2%, then you must make heavy use of org-mode. :-)

> One of the main things I have used Planner for is to publish a website
> from my notes. I see that org makes nice html output from a given
> page, but I have some questions about its configurability.
>
> 1. Is there a way to completely suppress the page header, or alter its
>    contents (for example, not listing author and date at the top of
>    all pages). Planner allows configurable html headers and
>    footers. I'd rather just have the title at the top, and put these
>    things at the bottom. I'd also like to put a set of common links
>    across the top of the page, as a sort of menubar, like many sites
>    have.

I guess we could have variables for the page header and footer that 
will be inserted there, with place holders for author name, date, and 
title.  This is a relative minor change.  The menu across the page 
could go in there, but I would suspect that you need to put this into 
the header format yourself.

Another possibility would be to put the header and footer information 
into a special section of the outline in the file, for example

* COMMENT html configuration
** Header
    here the header HTML code which will be inlined into the exported 
file
** Footer
    here the footer HTML code which will be inlined into the exported 
file

> 2. I want to publish a set of interlinked, related pages as a
>    "project."

Let me start with some background.  One of the main differences between 
planner and org-mode is that planner was built from the start for 
publishing, org-mode not.  Planner was based originally on Emacs wiki, 
and now is based on Muse.  These are both authoring tools, mainly done 
for publishing to a variety of formats.  Planner is just riding on top 
of these.  So the publishing ability you describe is not really 
planner, its is Emacs wiki, or Muse.

Because of this background, planner adopts the approach of many small 
interlinked files that can be published as a set of interrelated files.

Org-mode on the other hand was designed initially as an organizing tool 
only.  It supports exporting HTML to allow putting a notes file on the 
web, but thats about it.  Org-mode files can be large and contain many 
projects, which is why the linking process focusses on internal linking 
in a file.  Links like [[My target]] link to another place in the same 
file, not to an external file.

>  I think it would be easy enough for me to write an elisp
>    function that runs through a list of *.org files I want to publish,
>    publishes each one in turn, and then uploads each file to my site
>    via Tramp. (This would approximate the way Planner publishes my
>    stuff. It would help if org would let you specify the folder that
>    html output is to go in, and if it allowed Tramp URLs.)

This is trivial to implement.  I guess the easy way would be to let 
org-mode export to the current directory as it does now, and then copy 
the file by whatever means to a destination.

What do you mean by TRAMP urls?

>    However, would inter-page links work? In Planner, the link
>    [[pagename]] takes me to the file "pagename.muse". Then when the
>    pages are published to html, it becomes a link to "pagename.html"
>    so that the pages link together correctly in both Emacs buffers and
>    in the web browser.

Inter-file links work like URLs, for example [[file:pagename.org]], so 
all you need to do is to add the "file:" handle in front of the file 
name, and you need to specify the extension explicitly.  Slightly more 
inconvenient than in planner, but easy enough.  It would not be hard to 
implement a switch in the exporter that would convert all "file:" links 
to .org files into "html:" links to an html file.

>    What about links to other external files? I have the following
>    directory structure in my Planner:
>    /home/dto/Plans    (my planner files)
>    /home/dto/e        (e-scripts, my *.el that i've written, and other
>                       publishable attachments)
>
>    I can make a link to [[../e/thisfile]] and as long as I replicate
>    the same directory structure on the webserver, the links resolve
>    correctly once the files are published to html.
>
>    This would seem crucial to my publishing a whole website of related
>    pages using org. How would I go about making this work in org?

Other external files are just as easy: [[file:../e/thisfile]].

> 3. Planner/muse allow image links. It will actually put the image in
>    the buffer for you, so long as it can find the file.

Org-mode has links to images as well, and the HTML output will contain 
the link.  I would have to check if the handling uses absolute or 
relative file paths, but that is also easily modified.  Inlining images 
into an Emacs buffer is something I rarely find useful (the most 
notable exception being preview-latex).

> 4. In howm-mode, one doesn't need to specify an explicit list of pages
>    to be searched; instead you give it a folder and everything in that
>    folder counts as a page. This makes it easy to make new pages/topics
>    (whereas in org it seems like I would have to add them manually to
>    the list.) This isn't a crisis, as I can always just write a script
>    to update the list based on what's in the folder (and share the
>    script so that other org users can take advantage.)

Well, if you start implementing something like a publishing project 
with org-mode, I guess you would assume that all .org files in a given 
folder are part of the project.  What is different in HOWM is that it 
will automatically create links in existing files to new files.  
Org-mode does not have a mechanism for that.  So the question here 
really is: How would you like the older files to interact with newer 
ones?

> 5. Is there a way to get TODO etc to publish as something besides <h4>?

TODO entries in org-mode are simply part of the outline tree.  Any 
outline item can be a TODO entry.  When exporting to HTML, the first 4 
outline levels become h1...h4, the remaining ones become itemized 
lists.  You can change this transition with the "H" switch in the 
export "#+OPTIONS" line, have a look in the manual.  Apart from that, 
there are no special HTML constructs currently to wrap the TODO 
entries.

> Let me know if I can help add these features to Orgmode. I would be
> happy to help contribute changes/solutions if a developer can point me
> in the right direction.

If I understand you correctly, you can and want to do Lisp coding 
yourself?

I would propose the following strategy.  You start by creating a 
project, something like org-publish.el.  In that you define what is 
needed to do a publishing project, i.e. variables holding the root 
directory of a project, the directory where to publish the files, and 
anything else.  I guess you can let yourself guide by how Emacs wiki 
and Muse do these things.

Then you write commands to visit each org-file in that directory in 
turn, call the exporter and ship off the resulting file to whatever 
destination you desire, along with any other non-.org files in the 
project directory.

I would make the required hooks in the existing HTML exporter.  As far 
as I can see this mainly means honoring relative path specifications 
correctly, and changing links to .org files from file: to http:.

You also think up a way to define the header and footers for these new 
files, and I would provide ways for you to pass these to the exporter.

With a setup like this, we can develop this relatively independently.  
When the dust settles, we can integrate the new code into org.el, or 
distribute it with it, if that is what you want.

- Carsten