You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
730 lines
17 KiB
730 lines
17 KiB
The following is a list of ideas of functionality which would be nice |
|
to have in `rst.el`. In the examples a ``@`` stands for the cursor. |
|
|
|
Convert to id |
|
============= |
|
|
|
* Convert the region to an HTML id |
|
|
|
* For instance "Eine Überschrift" to "eine-berschrift" |
|
|
|
* According the same rules as reST does this |
|
|
|
Jump to internal target |
|
======================= |
|
|
|
* A command to jump to the internal target the point is on |
|
|
|
* A target may be |
|
|
|
* A section title |
|
|
|
* Footnotes / citations |
|
|
|
* Inline internal targets |
|
|
|
* Hyperlink target definition |
|
|
|
* Substitution definition |
|
|
|
* See hunk #26 in `rst_el-emacs_V23_1_patch1_1_2` vs. `emacs_V23_1` |
|
for some ideas |
|
|
|
Completion for directive options |
|
================================ |
|
|
|
* Imagine :: |
|
|
|
.. list-table:: |
|
:@ |
|
|
|
with the cursor at the asterisk |
|
|
|
* There should be a command which offers all the possible options for |
|
this particular directive as completion |
|
|
|
* May be `skeleton.el` can also be useful |
|
|
|
Completion for directives |
|
========================= |
|
|
|
* Imagine :: |
|
|
|
.. @ |
|
|
|
* There should be a command which offers all directives as completion |
|
|
|
* May be this should work for other keywords as well |
|
|
|
* May be this could work even at the beginning of the line |
|
|
|
* Completion must be bound to M-TAB |
|
|
|
* Already existing binding must be chained |
|
|
|
* May be `expand.el` can help (look in package finder)? |
|
|
|
* May be `hippie` is good here |
|
|
|
* Check `(info)autotype` |
|
|
|
Completion for user-defined elements |
|
==================================== |
|
|
|
* Imagine :: |
|
|
|
|@ |
|
|
|
or :: |
|
|
|
[@ |
|
|
|
or :: |
|
|
|
_@ |
|
|
|
* There should be a command which offers all defined substitutions / |
|
footnotes / links as completion |
|
|
|
Insertion of link alias |
|
======================= |
|
|
|
* Imagine :: |
|
|
|
Aspect of something |
|
=================== |
|
|
|
This is about the `aspect of something`_@ |
|
|
|
* There should be a command which asks you for an alias for the link, |
|
add the alias and change the link :: |
|
|
|
.. _aspects of something: |
|
|
|
Aspect of something |
|
=================== |
|
|
|
This is about the `aspects of something`_@ |
|
|
|
Smart use of `iimage-mode` |
|
========================== |
|
|
|
* There is `iimage-mode` which shows ``.. image::``\s in Emacs |
|
|
|
* May be we can add a binding to toggle it |
|
|
|
TOC in speedbar |
|
=============== |
|
|
|
* If the TOC is displayed in the speedbar this could be used for |
|
permanent navigation |
|
|
|
* Probably `imenu` functionality can be used for this |
|
|
|
* See `imenu` documentation and `speedbar-use-imenu-flag` |
|
|
|
* See `speedbar` |
|
|
|
toc-mode without markup |
|
======================= |
|
|
|
* The markup which may be contained in a section title is not useful |
|
in toc-mode and should be suppressed |
|
|
|
Sophisticated navigation in sections |
|
==================================== |
|
|
|
* Navigation in sections similar to navigation in other structured data |
|
|
|
* Like XML, Lisp |
|
|
|
* C-M-u für Up |
|
|
|
* C-M-d für Down |
|
|
|
* C-M-f / C-M-b für Forward / Backward |
|
|
|
Display of current location |
|
=========================== |
|
|
|
* Display the "section path" to the current point |
|
|
|
* Like in XML: In which element is the point? |
|
|
|
toc-mode only to a certain level |
|
================================ |
|
|
|
* If a TOC buffer is created a prefix argument should limit the depth |
|
of the listing to the given level |
|
|
|
Imenu support or similar |
|
======================== |
|
|
|
* Imenu could be supported |
|
|
|
* See `(elisp)Imenu` |
|
|
|
* `etags` could be supported |
|
|
|
* See `(emacs)Tags` and `etags.el` |
|
|
|
* May be this can be used for generating HTML local tags somehow? |
|
|
|
* As requested by `Convert to id`_ |
|
|
|
* Could use `complete-tag` |
|
|
|
Outline support |
|
=============== |
|
|
|
* Support for `outline-mode` / `allout-mode` would be nice |
|
|
|
* Should consider section titles |
|
|
|
* May be item lists can also be included |
|
|
|
* Using `allout-mode` is difficult |
|
|
|
* It's not customizable enough for the complex syntax of |
|
reStructuredText |
|
|
|
* However, some commands make sense |
|
|
|
* Motion commands |
|
|
|
* Exposure commands |
|
|
|
* Some alteration commands |
|
|
|
* Should be reimplemented |
|
|
|
* Key bindings need to be reused |
|
|
|
* However, care must be taken if a file uses `allout-mode` for |
|
instance by comment strings |
|
|
|
* In this case key bindings must not be overridden |
|
|
|
* A command adding / updating `allout-mode` tags could be a solution |
|
|
|
Sophisticated filling |
|
===================== |
|
|
|
* These things must be filled special: |
|
|
|
* Definitions |
|
|
|
* Filling of :: |
|
|
|
* VeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURL |
|
|
|
should work as expected by *not* breaking the line |
|
|
|
* May be `fill-nobreak-predicate` can help here |
|
|
|
* These things may not be filled at all |
|
|
|
* Literal blocks |
|
|
|
* Tables |
|
|
|
* Link definitions |
|
|
|
* May be `fill-nobreak-predicate` can help here, too |
|
|
|
* May be defining an own `auto-fill-function` may be useful |
|
|
|
* Might prevent auto-filling of literal text |
|
|
|
* Filling of a re-indented item doesn't work as expected:: |
|
|
|
* Something just indented once more by the user |
|
though continuation line is not indented already |
|
|
|
* Alternatively indentation could indent the whole item |
|
|
|
* See `Sophisticated indentation`_ |
|
|
|
* See also `Filling of section headers`_ |
|
|
|
Sophisticated indentation |
|
========================= |
|
|
|
* It should be generally possible to shift one more to the right |
|
|
|
* This makes indentation for quotes possible |
|
|
|
* But not for literal blocks |
|
|
|
* For item lists the best tab should be on the same level as the last |
|
item:: |
|
|
|
* bla |
|
|
|
@ |
|
|
|
* The second best tab should be where text starts:: |
|
|
|
* bla |
|
|
|
@ |
|
|
|
* <backtab> should be used to indent in the other direction |
|
|
|
* Or may be C-u <tab> but this has a different meaning |
|
|
|
* <tab> could obsolete C-c C-r <tab> |
|
|
|
* For this the indentation needs to be determined at the start |
|
instead of per line |
|
|
|
* <tab> over list works:: |
|
|
|
Text |
|
|
|
* GGGGGG |
|
* SSSSSSSSSSSSSSS |
|
* TTTTTTTT |
|
* ZZZZZZZZ |
|
|
|
* <tab> over list doesn't work:: |
|
|
|
Text |
|
|
|
* GGGGGG |
|
* SSSSSSSSSSSSSSS |
|
* TTTTTTTT |
|
* ZZZZZZZZ |
|
|
|
* An indenting tab on the head of a list item should indent the whole |
|
list item instead of only the first line |
|
|
|
* Alternatively `fill-paragraph` could do so |
|
|
|
* See `Sophisticated filling`_ |
|
|
|
* May be `refill-mode` can be useful |
|
|
|
List to sections |
|
================ |
|
|
|
* A command would be nice which |
|
|
|
* transforms the first level of a nested list in a region into a |
|
header |
|
|
|
* removes one level of indentation from the rest of the list |
|
|
|
Change section level by more than one step |
|
========================================== |
|
|
|
* It would be nice if <C-h> `rst-adjust` could rotate a section |
|
adornment more than one level |
|
|
|
* A modification of the semantic of the prefix arguments could do this |
|
|
|
* Non-zero numeric prefix arg n rotates n step in the given direction |
|
|
|
* Prefix arg 0 toggles overline / underline |
|
|
|
* This would be different from current setup |
|
|
|
Compiling for syntax check |
|
========================== |
|
|
|
* Compiling with results going to `/dev/null` would be useful |
|
|
|
* This would just do a syntax check with no files lying around |
|
|
|
* Toolset choice for <C-c C-c C-c> `rst-compile` must be by |
|
customizable if at all necessary |
|
|
|
* Customization group must be used |
|
|
|
Renumber an exisiting enumeration |
|
================================= |
|
|
|
* Renumbering an exisiting enumeration is not possible yet |
|
|
|
Command to move across blocks |
|
============================= |
|
|
|
* A command moving forward / backward across the content blocks of the |
|
current block would be nice |
|
|
|
* For instance: Move across all blocks contained in an item or field |
|
|
|
* This would move to the start of the sibling of the current block |
|
|
|
* Would allow to jump to the next item on the same level in a list |
|
|
|
* <C-M-f> `forward-sexp` could be a nice binding |
|
|
|
rst-toc-insert features |
|
======================= |
|
|
|
* The `contents::` options could be parsed to figure out how deep to |
|
render the inserted TOC |
|
|
|
* On load, detect any existing TOCs and set the properties for links |
|
|
|
* TOC insertion should have an option to add empty lines |
|
|
|
* TOC insertion should deal with multiple lines |
|
|
|
* Automatically detect if we have a `section-numbering::` in the |
|
corresponding section, to render the toc. |
|
|
|
Automatic handling of `.txt` files |
|
================================== |
|
|
|
It would be nice to differentiate between text files using |
|
reStructuredText and other general text files. If we had a function to |
|
automatically guess whether a `.txt` file is following the |
|
reStructuredText conventions, we could trigger `rst-mode` without |
|
having to hard-code this in every text file, nor forcing the user to |
|
add a local mode variable at the top of the file. We could perform |
|
this guessing by searching for a valid adornment at the top of the |
|
document or searching for reStructuredText directives further on. |
|
|
|
Entry level for rst-straighten-adornments |
|
========================================= |
|
|
|
* `rst-straighten-adornments` should have an entry level to start at a |
|
lower than the top level |
|
|
|
* I for one prefer a verbose style for top level titles which is not |
|
appropriate for documents without titles |
|
|
|
* Should be done by a prefix argument |
|
|
|
Support for ispell |
|
================== |
|
|
|
* `ispell` may skip certain things |
|
|
|
* Using `ispell-skip-region-alist` |
|
|
|
* ``Code`` should be skipped |
|
|
|
* Literal text after ``::`` should be skipped |
|
|
|
* A customization should switch this on so users are not surprised |
|
|
|
Marriage with `forms-mode` |
|
========================== |
|
|
|
* Like I married `forms-mode` with `sdf-mode` |
|
|
|
* Would allow editing a number of records with a fixed layout |
|
|
|
* The base reStructuredText file should be either |
|
|
|
* a list consisting of field lists |
|
|
|
* The separator needs to be defined, however |
|
|
|
* A section header or transition may be a useful separator |
|
|
|
* a `list-table` |
|
|
|
* a CSV file |
|
|
|
* That would call for a general support for CSV support for forms |
|
|
|
* May be `orgtbl-to-csv` in `org/org-table.el` could be useful for |
|
this |
|
|
|
Marriage with `org-mode` |
|
======================== |
|
|
|
* May be Org mode can be utilized instead of `forms-mode` |
|
|
|
* See `orgtbl-mode` |
|
|
|
* See `orgstruct-mode` |
|
|
|
* Though this looks more like `allout-mode` |
|
|
|
Intelligent quote insertion |
|
=========================== |
|
|
|
* Use or develop something like `insert-pair` |
|
|
|
* Main use for forgotten quoting |
|
|
|
* Thus may rather quote preceding word than following one |
|
|
|
* If `forward-sexp` could be overridden `insert-pair` might me |
|
usable directly |
|
|
|
* Also add something like `delete-pair` |
|
|
|
Sophisticated alignment |
|
======================= |
|
|
|
* May be aligning can be used to get results like this |
|
|
|
:Some: Field |
|
|
|
:Longer name: Aligned |
|
|
|
:Even longer name: More aligned |
|
|
|
* See `align.el` |
|
|
|
toc-mode per buffer |
|
=================== |
|
|
|
* At the moment there can only be globally one TOC |
|
|
|
* A TOC could be separate for each buffer |
|
|
|
toc-mode could generate reST |
|
============================ |
|
|
|
* The format of the generated TOC could be reStructuredText |
|
|
|
* For instance as a bullet list |
|
|
|
* So it could be copied and basted into a reStructuredText document |
|
|
|
* Conversion could be done in toc-mode buffer |
|
|
|
* An alternative could be that `rst-bullet-list-region` handles |
|
indented text properly |
|
|
|
Improvements for comments |
|
========================= |
|
|
|
* `comment-use-syntax` should be set to nil locally |
|
|
|
* `comment-forward` should work so `comment-dwim` recognizes a |
|
commented region |
|
|
|
* Then it could uncomment it automatically and use of prefix |
|
argument is no longer neccessary |
|
|
|
Context sensitive M-q |
|
===================== |
|
|
|
* M-q / `fill-paragraph` should check whether point is in section |
|
header and call `rst-adjust` in this case |
|
|
|
* This would unify handling of changes in section headers and normal |
|
paragraphs |
|
|
|
Switch to using `cl-lib` |
|
======================== |
|
|
|
* Options to use `cl-lib` |
|
|
|
There are various options, and you'll have to judge for yourself which |
|
is best for your particular case: |
|
- live with the warnings. |
|
- switch to cl-lib and ask users of older Emacsen to install cl-lib |
|
(available in GNU ELPA). |
|
- add things like (unless (fboundp 'cl-letf) (defalias 'cl-letf 'letf)). |
|
- change the code to use something else (e.g. for flet, you can switch |
|
to using either defadvice or (let ((f1 (lambda ..))) ...). |
|
- ... |
|
|
|
-- Stefan Monnier |
|
|
|
* Remove own implementations then |
|
|
|
Filling of section headers |
|
========================== |
|
|
|
* Filling should recognize section headers and adjust the adornment |
|
|
|
* Then a fill operation for a region wouldn't break the section |
|
header adornment |
|
|
|
* In addition a fill operation could be used instead of adjusting a |
|
section header |
|
|
|
Cursor after adjusting adornment |
|
================================ |
|
|
|
* Adjusting a section header should move the cursor to the end of the |
|
adornment |
|
|
|
* Then a following C-j / Return opens a new line instead of breaking |
|
the adornment just created |
|
|
|
Copying literal blocks |
|
====================== |
|
|
|
* Copying literal blocks should eat up the block indentation |
|
|
|
* This way code fragments can be copied without removing the block |
|
indentation by hand |
|
|
|
Structural operations for toc-mode |
|
================================== |
|
|
|
* Structrual operations for toc-mode |
|
|
|
* Raise or lower sections |
|
|
|
* Move sections around |
|
|
|
Inhibit auto-fill in literal blocks |
|
=================================== |
|
|
|
* In a literal block a space should not do auto-fill |
|
|
|
* May be variable `normal-auto-fill-function` can be set mode |
|
specific |
|
|
|
* Is normally `do-auto-fill` |
|
|
|
toc-mode should leave mark |
|
========================== |
|
|
|
* When you jump to a different point in the document by using toc-mode |
|
the mark should be set at the point of departure |
|
|
|
* This aligns with the semantic of other far jumps in the document |
|
such as `beginning-of-buffer` |
|
|
|
Remembering last location per section |
|
===================================== |
|
|
|
* Remembering the last location per section would make it possible to |
|
jump back to this location |
|
|
|
* This is useful if several sections are worked on in parallel |
|
|
|
* The jump into the section could happen from toc-mode |
|
|
|
* Instead of to the section header |
|
|
|
* May be by a special key |
|
|
|
* Other section based jump commands could do similar |
|
|
|
* For instance navigating by sections |
|
|
|
* This calls for a general modifier for jumps |
|
|
|
Multiple steps for `rst-adjust` |
|
=============================== |
|
|
|
* Sometimes it's useful to adjust more than one step in the given |
|
direction |
|
|
|
* For instance to follow a 2= title by 1= normal header skipping the |
|
usual 2- level |
|
|
|
* Therefore using a counter may be useful |
|
|
|
Enhance compilation support |
|
=========================== |
|
|
|
* Compilation to ODT should be supported |
|
|
|
* Arbitrary compilations should be supported using customization |
|
|
|
* Key must be configurable |
|
|
|
* Command must be configurable |
|
|
|
* May be the whole toolset stuff needs to be replaced? |
|
|
|
Support for longlines mode |
|
========================== |
|
|
|
* `longlines-mode` should use correct indentation for broken lines |
|
|
|
* This is actually an enhancement of `longlines-mode` |
|
|
|
* `longlines-mode` modifies the buffer |
|
|
|
* This is needed to use all the standard functionality like |
|
`move-to-column` |
|
|
|
* Using property `display` for inserting indentation does not work |
|
properly because of this |
|
|
|
* Indentation must be inserted in the buffer |
|
|
|
* However, it needs to have the property `intangible` so it can |
|
not be modified |
|
|
|
* See `Emacs Lisp => 32.19 Text Properties => Special |
|
Properties` |
|
|
|
* It would be nice to also have a visible indication for being |
|
automatic insertion |
|
|
|
* Such indentation must be removed by `longlines-encode-*` |
|
|
|
* Probably it should be marked by a special property such as |
|
`longlines-indentation` |
|
|
|
* `longlines-wrap-line` needs a hook called after replacing the |
|
blank by a soft newline |
|
|
|
* May be `longlines-*search-*` needs to be adapted as well? |
|
|
|
Indent correctly |
|
================ |
|
|
|
* `rst-shift-region` should have a mode to indent correctly |
|
|
|
* I.e.: Indent the region according to the tab given by the line |
|
above |
|
|
|
* But see also `Copying literal blocks`_ |
|
|
|
Jumps leaving mark |
|
================== |
|
|
|
* All jumps across a wider distance should push the mark on the local |
|
mark ring |
|
|
|
* See C-u C-SPC documentation |
|
|
|
* Jumps to section titles |
|
|
|
* That would result in jumping back to TOC which is especially |
|
useful for an internal TOC |
|
|
|
* But not jumps to paragraphs |
|
|
|
* Jumps with C-M-a / C-M-e? |
|
|
|
TOC controlling sliding window |
|
============================== |
|
|
|
* `toc-mode` must have a mode where cursor entering a new line moves |
|
to the respective section in another window |
|
|
|
* So one can browse through a buffer by using the TOC |
|
|
|
Jump to list entry on same level |
|
================================ |
|
|
|
* If on a list entry of some sort there should be a way to navigate to |
|
a sibling |
|
|
|
* Forward and backward |
|
|
|
* May be also up and down |
|
|
|
`rst-shift-region` shifts as needed |
|
=================================== |
|
|
|
* `rst-shift-region` should have an option to "do the right thing" |
|
|
|
* In particular it should shift as needed by the text above |
|
|
|
* This makes indentation of an inserted block easier because you |
|
don't need to know the correct number of tabs |
|
|
|
* There should be an option to "align under", "align same" and |
|
"align less" |
|
|
|
* May be this could be commanded by one or more C-u's
|
|
|