Re: searchable refcard?

From: Carsten Dominik <carsten.dominik@gmail.com>
To: "Alan E. Davis" <lngndvs@gmail.com>
Cc: emacs-orgmode@gnu.org,
	Nathaniel Cunningham <nathaniel.cunningham@gmail.com>
Subject: Re: searchable refcard?
Date: Sun, 30 Nov 2008 09:54:48 +0100	[thread overview]
Message-ID: <EBCDBA94-285D-458C-A6C0-AF4F6DDC3DAB@gmail.com> (raw)
In-Reply-To: <7bef1f890811271844o5231d38ct13e1a0bf14c851c9@mail.gmail.com>

Hi Alan,

I have been thinking about this some more.  As Nat has pointed
out, the problem with the pdf can be fixed by using pdftex to
produce it, and maybe I should improve my standard procedure
to do just that.

OK, about a separate, new, searchable reference written in
Org-mode.  First of all, I am not sure if automatic production
can be made to work well.  Second, the PDF reference card has
been squeezed and optimized a lot to fit on a single A4, it is
as comprehensive as possible with this restriction, but incomplete
nonetheless.  In particular the meaning of prefix arguments
is often not mentioned, and some less important keys are not given.

With this restriction gone, we could make a *better* quick
reference, and I think we should seize this opportunity.
I can see two ways to do this.

1. Make a much more comprehensive reference by copying
all the key descriptions from the manual.  This would mean
going into the TeXInfo source and basically extracting everything
in the
     @table @kbd .... @end table
sections, with appropriate headings.  This would make a quite long
reference, may be too long and too much duplication compared to the
manual itself.

2. Start from the current tex file for the quick reference
  and then go through the manual to see if things are
  missing and add them, in a similarly compact way.
  Or, even easier, start from the org-help you published
  earlier, but still make an effort to make this more complete.

I think (2) may be more realistic, and I would be willing to help
fill in missing things, I think I know quite well which these are.
Examples can be taken from things that are still in the
orgcard.tex file but are commented out to save space.  Another thing
that would be good is a summary of the Markup Rules, of
Export options specified with #+OPTIONS, #+TITLE etc,
of #+STARTUP stuff etc.

Another thing to improve is lines like this:

    - archive the subtree                               $ / a / A

This is too compact and does not say what kind of archiving
will be done with each of these keys.

Keeping this reference up-to-date would be relatively simple,
because I do mention all changed key bindings in the release note.
So maintaining this reference would mean carefully reading the Notes
for each official release and adding/changing 1 or 2 lines of
the reference.

- Carsten

On Nov 28, 2008, at 3:44 AM, Alan E. Davis wrote:

> I think I can do this.  Before I make a decision, it seems terribly
> important to understand what is a "searchable refcard."  I answered
> the original post in part because the term was unclear to me.  A
> "refcard" is something I print out on a sheet and reference as needed.
>
> You are referring then to a searchable reference accessible as an org
> file?  Similar to what I posted to the list?  What would make this
> file more searchable?
>
> I apologize if my questions seem impertinent.  I would be willing to
> clean up and provide a file "org-help.org" periodically, as changes
> occurred in orgcard.tex.  Even better, if I can see a way to extract
> this information from the source, it would be possible to keep it more
> up to date.
>
> Alan
>
> On 11/28/08, Carsten Dominik <dominik@science.uva.nl> wrote:
>> Hi Alan,
>>
>> the refcard is done by hand, a lot of fiddling goes into
>> fitting all this info on two pages.  And  don't want to
>> keep two versions.
>>
>> That said, my refcard is incomplete due to space constraints, and it
>> may be worth to do a better one, searchable, in Org.  Maybe you would
>> like to maintain it?
>>
>> This is little work, you can just look at the changes in the
>> orgcard.tex file - basically it never changes, or hardly ever.
>>
>> - Carsten
>>
>> I
>> On Nov 27, 2008, at 1:17 PM, Alan E. Davis wrote:
>>
>>> I hope I don't make a nuisance of myself by responding to this.  I
>>> posted at some earlier date about my idea of making an org-help file
>>> "help.org" that I can call up with a keystroke.  This is an
>>> extension of the texinfo concept, perhaps, or a subset of it.
>>>
>>> I think this would best be done in texinfo, and generate a rough
>>> equivalent of the refcard's contents (keybindings reference and
>>> brief notes), separate from the org mode info document.   I looked
>>> at texinfo, and even though I can write fairly sophisticated
>>> material in LaTeX, texinfo looks daunting enough to discourage me
>>> from trying.
>>>
>>> For now, I have borrowed the idea of publishing a text refcard, but
>>> in org-mode.  The reference card is then folded in outline format.
>>> I have been doing the converstion by hand from orgcard.tex, by using
>>> the untex command to generate a rough text file, and then taking
>>> several passes through the file to setup headlines and format the
>>> lines.  This can all be done in one or two steps, with a short elisp
>>> function, but I haven't had the time to brush up on elisp (I notice
>>> it's a moving target, as well).
>>>
>>> The upshot for now may be a kludge, but it's extremeliy useful on a
>>> day to day basis.  See help.org, attached.  No warantees implied.
>>>
>>> That brought me to the question of how is the refcard written and
>>> kept up to date?  Possibly from other files in the org repository?
>>> Or is it separately written up each time?  It is usually up to date
>>> with the newest version of org-mode, at least insofar as the version
>>> number.
>>>
>>> With apologies,
>>>
>>> Alan
>>>
>>> On Thu, Nov 27, 2008 at 8:07 PM, Sebastian Rose
>>> <sebastian_rose@gmx.de> wrote:
>>> Hi Nathaniel,
>>>
>>>
>>> I don't know what causes this trouble, but I faced this sometimes  
>>> with
>>> LaTeX generated PDFs. Might be an encoding problem or what ever.
>>>
>>>
>>> The LaTeX sources are available at repo.or.cz, as is the entire Org-
>>> mode
>>> package:
>>>
>>> http://repo.or.cz/w/org-mode.git?a=blob;f=doc/orgcard.tex;h=8e2cbe0d76f9b71997c106982911b144ed5eff2f;hb=HEAD
>>>
>>>
>>> Regards,
>>>
>>> Sebastian
>>>
>>>
>>> "Nathaniel Cunningham" <nathaniel.cunningham@gmail.com> writes:
>>>> Greetings,
>>>> I can't search the PDF version of the org-mode refcard (in a
>>> couple of
>>>> different apps on Mac OS X).  I can match single-character
>>> strings, and it
>>>> appears that my reader apps see spaces between e v e r y s i n g l
>>> e c h a r
>>>> a c t e r, which causes my trouble.  (Not a typical problem I have
>>> with
>>>> these apps.)
>>>>
>>>> Is a more search-friendly version, or the (presumably LaTeX)
>>> source, of the
>>>> refcard available?
>>>>
>>>> Cheers,
>>>> Nathaniel
>>>> [please include me  ( nathaniel.cunningham@gmail.com ) on any
>>> replies, as
>>>> I'm not a member of this list]
>>>> _______________________________________________
>>>> Emacs-orgmode mailing list
>>>> Remember: use `Reply All' to send replies to the list.
>>>> Emacs-orgmode@gnu.org
>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>
>>> --
>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449
>>> Hannover
>>>
>>> Tel.:  +49 (0)511 - 36 58 472
>>> Fax:   +49 (0)1805 - 233633 - 11044
>>> mobil: +49 (0)173 - 83 93 417
>>> Email: s.rose emma-stil de, sebastian_rose gmx de
>>> Http:  www.emma-stil.de
>>>
>>>
>>> _______________________________________________
>>> Emacs-orgmode mailing list
>>> Remember: use `Reply All' to send replies to the list.
>>> Emacs-orgmode@gnu.org
>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>
>>>
>>>
>>> --
>>> Alan Davis
>>>
>>> "It's never a matter of liking or disliking ..."
>>>   ---Santa Ynez Chumash Medicine Man
>>>
>>> <help.org>_______________________________________________
>>> Emacs-orgmode mailing list
>>> Remember: use `Reply All' to send replies to the list.
>>> Emacs-orgmode@gnu.org
>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>
>>
>
>
> -- 
> Alan Davis
>
> "It's never a matter of liking or disliking ..."
>    ---Santa Ynez Chumash Medicine Man