1The following is a list of ideas of functionality which would be nice 2to have in `rst.el`. In the examples a ``@`` stands for the cursor. 3 4Convert to id 5============= 6 7* Convert the region to an HTML id 8 9 * For instance "Eine Überschrift" to "eine-uberschrift" 10 11 * According the same rules as reST does this 12 13Jump to internal target 14======================= 15 16* A command to jump to the internal target the point is on 17 18* A target may be 19 20 * A section title 21 22 * Footnotes / citations 23 24 * Inline internal targets 25 26 * Hyperlink target definition 27 28 * Substitution definition 29 30* See hunk #26 in `rst_el-emacs_V23_1_patch1_1_2` vs. `emacs_V23_1` 31 for some ideas 32 33Completion for directive options 34================================ 35 36* Imagine :: 37 38 .. list-table:: 39 :@ 40 41 with the cursor at the asterisk 42 43* There should be a command which offers all the possible options for 44 this particular directive as completion 45 46* May be `skeleton.el` can also be useful 47 48Completion for directives 49========================= 50 51* Imagine :: 52 53 .. @ 54 55* There should be a command which offers all directives as completion 56 57* May be this should work for other keywords as well 58 59* May be this could work even at the beginning of the line 60 61* Completion must be bound to M-TAB 62 63 * Already existing binding must be chained 64 65 * May be `expand.el` can help (look in package finder)? 66 67 * May be `hippie` is good here 68 69 * Check `(info)autotype` 70 71Completion for user-defined elements 72==================================== 73 74* Imagine :: 75 76 |@ 77 78 or :: 79 80 [@ 81 82 or :: 83 84 _@ 85 86* There should be a command which offers all defined substitutions / 87 footnotes / links as completion 88 89Insertion of link alias 90======================= 91 92* Imagine :: 93 94 Aspect of something 95 =================== 96 97 This is about the `aspect of something`_@ 98 99* There should be a command which asks you for an alias for the link, 100 add the alias and change the link :: 101 102 .. _aspects of something: 103 104 Aspect of something 105 =================== 106 107 This is about the `aspects of something`_@ 108 109Smart use of `iimage-mode` 110========================== 111 112* There is `iimage-mode` which shows ``.. image::``\s in Emacs 113 114* May be we can add a binding to toggle it 115 116TOC in speedbar 117=============== 118 119* If the TOC is displayed in the speedbar this could be used for 120 permanent navigation 121 122 * Probably `imenu` functionality can be used for this 123 124 * See `imenu` documentation and `speedbar-use-imenu-flag` 125 126 * See `speedbar` 127 128toc-mode without markup 129======================= 130 131* The markup which may be contained in a section title is not useful 132 in toc-mode and should be suppressed 133 134Sophisticated navigation in sections 135==================================== 136 137* Navigation in sections similar to navigation in other structured data 138 139 * Like XML, Lisp 140 141 * C-M-u für Up 142 143 * C-M-d für Down 144 145 * C-M-f / C-M-b für Forward / Backward 146 147Display of current location 148=========================== 149 150* Display the "section path" to the current point 151 152* Like in XML: In which element is the point? 153 154toc-mode only to a certain level 155================================ 156 157* If a TOC buffer is created a prefix argument should limit the depth 158 of the listing to the given level 159 160Imenu support or similar 161======================== 162 163* Imenu could be supported 164 165 * See `(elisp)Imenu` 166 167* `etags` could be supported 168 169 * See `(emacs)Tags` and `etags.el` 170 171 * May be this can be used for generating HTML local tags somehow? 172 173 * As requested by `Convert to id`_ 174 175 * Could use `complete-tag` 176 177Outline support 178=============== 179 180* Support for `outline-mode` / `allout-mode` would be nice 181 182 * Should consider section titles 183 184 * May be item lists can also be included 185 186 * Using `allout-mode` is difficult 187 188 * It's not customizable enough for the complex syntax of 189 reStructuredText 190 191 * However, some commands make sense 192 193 * Motion commands 194 195 * Exposure commands 196 197 * Some alteration commands 198 199 * Should be reimplemented 200 201 * Key bindings need to be reused 202 203 * However, care must be taken if a file uses `allout-mode` for 204 instance by comment strings 205 206 * In this case key bindings must not be overridden 207 208 * A command adding / updating `allout-mode` tags could be a solution 209 210Sophisticated filling 211===================== 212 213* These things must be filled special: 214 215 * Definitions 216 217 * Filling of :: 218 219 * VeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURLVeryLongWordSuchAsAnURL 220 221 should work as expected by *not* breaking the line 222 223 * May be `fill-nobreak-predicate` can help here 224 225* These things may not be filled at all 226 227 * Literal blocks 228 229 * Tables 230 231 * Link definitions 232 233 * May be `fill-nobreak-predicate` can help here, too 234 235* May be defining an own `auto-fill-function` may be useful 236 237 * Might prevent auto-filling of literal text 238 239* Filling of a re-indented item doesn't work as expected:: 240 241 * Something just indented once more by the user 242 though continuation line is not indented already 243 244 * Alternatively indentation could indent the whole item 245 246 * See `Sophisticated indentation`_ 247 248* See also `Filling of section headers`_ 249 250Sophisticated indentation 251========================= 252 253* It should be generally possible to shift one more to the right 254 255 * This makes indentation for quotes possible 256 257 * But not for literal blocks 258 259* For item lists the best tab should be on the same level as the last 260 item:: 261 262 * bla 263 264 @ 265 266 * The second best tab should be where text starts:: 267 268 * bla 269 270 @ 271 272* <backtab> should be used to indent in the other direction 273 274 * Or may be C-u <tab> but this has a different meaning 275 276* <tab> could obsolete C-c C-r <tab> 277 278 * For this the indentation needs to be determined at the start 279 instead of per line 280 281 * <tab> over list works:: 282 283 Text 284 285 * GGGGGG 286 * SSSSSSSSSSSSSSS 287 * TTTTTTTT 288 * ZZZZZZZZ 289 290 * <tab> over list doesn't work:: 291 292 Text 293 294 * GGGGGG 295 * SSSSSSSSSSSSSSS 296 * TTTTTTTT 297 * ZZZZZZZZ 298 299* An indenting tab on the head of a list item should indent the whole 300 list item instead of only the first line 301 302 * Alternatively `fill-paragraph` could do so 303 304 * See `Sophisticated filling`_ 305 306* May be `refill-mode` can be useful 307 308List to sections 309================ 310 311* A command would be nice which 312 313 * transforms the first level of a nested list in a region into a 314 header 315 316 * removes one level of indentation from the rest of the list 317 318Change section level by more than one step 319========================================== 320 321* It would be nice if <C-h> `rst-adjust` could rotate a section 322 adornment more than one level 323 324* A modification of the semantic of the prefix arguments could do this 325 326 * Non-zero numeric prefix arg n rotates n step in the given direction 327 328 * Prefix arg 0 toggles overline / underline 329 330 * This would be different from current setup 331 332Compiling for syntax check 333========================== 334 335* Compiling with results going to `/dev/null` would be useful 336 337 * This would just do a syntax check with no files lying around 338 339* Toolset choice for <C-c C-c C-c> `rst-compile` must be by 340 customizable if at all necessary 341 342 * Customization group must be used 343 344Renumber an exisiting enumeration 345================================= 346 347* Renumbering an exisiting enumeration is not possible yet 348 349Command to move across blocks 350============================= 351 352* A command moving forward / backward across the content blocks of the 353 current block would be nice 354 355 * For instance: Move across all blocks contained in an item or field 356 357 * This would move to the start of the sibling of the current block 358 359 * Would allow to jump to the next item on the same level in a list 360 361* <C-M-f> `forward-sexp` could be a nice binding 362 363rst-toc-insert features 364======================= 365 366* The `contents::` options could be parsed to figure out how deep to 367 render the inserted TOC 368 369* On load, detect any existing TOCs and set the properties for links 370 371* TOC insertion should have an option to add empty lines 372 373* TOC insertion should deal with multiple lines 374 375* Automatically detect if we have a `section-numbering::` in the 376 corresponding section, to render the toc. 377 378Automatic handling of `.txt` files 379================================== 380 381It would be nice to differentiate between text files using 382reStructuredText and other general text files. If we had a function to 383automatically guess whether a `.txt` file is following the 384reStructuredText conventions, we could trigger `rst-mode` without 385having to hard-code this in every text file, nor forcing the user to 386add a local mode variable at the top of the file. We could perform 387this guessing by searching for a valid adornment at the top of the 388document or searching for reStructuredText directives further on. 389 390Entry level for rst-straighten-adornments 391========================================= 392 393* `rst-straighten-adornments` should have an entry level to start at a 394 lower than the top level 395 396 * I for one prefer a verbose style for top level titles which is not 397 appropriate for documents without titles 398 399 * Should be done by a prefix argument 400 401Support for ispell 402================== 403 404* `ispell` may skip certain things 405 406 * Using `ispell-skip-region-alist` 407 408 * ``Code`` should be skipped 409 410 * Literal text after ``::`` should be skipped 411 412 * A customization should switch this on so users are not surprised 413 414Marriage with `forms-mode` 415========================== 416 417* Like I married `forms-mode` with `sdf-mode` 418 419* Would allow editing a number of records with a fixed layout 420 421* The base reStructuredText file should be either 422 423 * a list consisting of field lists 424 425 * The separator needs to be defined, however 426 427 * A section header or transition may be a useful separator 428 429 * a `list-table` 430 431 * a CSV file 432 433 * That would call for a general support for CSV support for forms 434 435 * May be `orgtbl-to-csv` in `org/org-table.el` could be useful for 436 this 437 438Marriage with `org-mode` 439======================== 440 441* May be Org mode can be utilized instead of `forms-mode` 442 443 * See `orgtbl-mode` 444 445 * See `orgstruct-mode` 446 447 * Though this looks more like `allout-mode` 448 449Intelligent quote insertion 450=========================== 451 452* Use or develop something like `insert-pair` 453 454 * Main use for forgotten quoting 455 456 * Thus may rather quote preceding word than following one 457 458 * If `forward-sexp` could be overridden `insert-pair` might me 459 usable directly 460 461* Also add something like `delete-pair` 462 463Sophisticated alignment 464======================= 465 466* May be aligning can be used to get results like this 467 468 :Some: Field 469 470 :Longer name: Aligned 471 472 :Even longer name: More aligned 473 474 * See `align.el` 475 476toc-mode per buffer 477=================== 478 479* At the moment there can only be globally one TOC 480 481 * A TOC could be separate for each buffer 482 483toc-mode could generate reST 484============================ 485 486* The format of the generated TOC could be reStructuredText 487 488 * For instance as a bullet list 489 490 * So it could be copied and basted into a reStructuredText document 491 492 * Conversion could be done in toc-mode buffer 493 494* An alternative could be that `rst-bullet-list-region` handles 495 indented text properly 496 497Improvements for comments 498========================= 499 500* `comment-use-syntax` should be set to nil locally 501 502* `comment-forward` should work so `comment-dwim` recognizes a 503 commented region 504 505 * Then it could uncomment it automatically and use of prefix 506 argument is no longer neccessary 507 508Context sensitive M-q 509===================== 510 511* M-q / `fill-paragraph` should check whether point is in section 512 header and call `rst-adjust` in this case 513 514 * This would unify handling of changes in section headers and normal 515 paragraphs 516 517Switch to using `cl-lib` 518======================== 519 520* Options to use `cl-lib` 521 522 There are various options, and you'll have to judge for yourself which 523 is best for your particular case: 524 - live with the warnings. 525 - switch to cl-lib and ask users of older Emacsen to install cl-lib 526 (available in GNU ELPA). 527 - add things like (unless (fboundp 'cl-letf) (defalias 'cl-letf 'letf)). 528 - change the code to use something else (e.g. for flet, you can switch 529 to using either defadvice or (let ((f1 (lambda ..))) ...). 530 - ... 531 532 -- Stefan Monnier 533 534* Remove own implementations then 535 536Filling of section headers 537========================== 538 539* Filling should recognize section headers and adjust the adornment 540 541 * Then a fill operation for a region wouldn't break the section 542 header adornment 543 544 * In addition a fill operation could be used instead of adjusting a 545 section header 546 547Cursor after adjusting adornment 548================================ 549 550* Adjusting a section header should move the cursor to the end of the 551 adornment 552 553 * Then a following C-j / Return opens a new line instead of breaking 554 the adornment just created 555 556Copying literal blocks 557====================== 558 559* Copying literal blocks should eat up the block indentation 560 561 * This way code fragments can be copied without removing the block 562 indentation by hand 563 564Structural operations for toc-mode 565================================== 566 567* Structrual operations for toc-mode 568 569 * Raise or lower sections 570 571 * Move sections around 572 573Inhibit auto-fill in literal blocks 574=================================== 575 576* In a literal block a space should not do auto-fill 577 578 * May be variable `normal-auto-fill-function` can be set mode 579 specific 580 581 * Is normally `do-auto-fill` 582 583toc-mode should leave mark 584========================== 585 586* When you jump to a different point in the document by using toc-mode 587 the mark should be set at the point of departure 588 589 * This aligns with the semantic of other far jumps in the document 590 such as `beginning-of-buffer` 591 592Remembering last location per section 593===================================== 594 595* Remembering the last location per section would make it possible to 596 jump back to this location 597 598 * This is useful if several sections are worked on in parallel 599 600* The jump into the section could happen from toc-mode 601 602 * Instead of to the section header 603 604 * May be by a special key 605 606* Other section based jump commands could do similar 607 608 * For instance navigating by sections 609 610* This calls for a general modifier for jumps 611 612Multiple steps for `rst-adjust` 613=============================== 614 615* Sometimes it's useful to adjust more than one step in the given 616 direction 617 618 * For instance to follow a 2= title by 1= normal header skipping the 619 usual 2- level 620 621* Therefore using a counter may be useful 622 623Enhance compilation support 624=========================== 625 626* Compilation to ODT should be supported 627 628* Arbitrary compilations should be supported using customization 629 630 * Key must be configurable 631 632 * Command must be configurable 633 634* May be the whole toolset stuff needs to be replaced? 635 636Support for longlines mode 637========================== 638 639* `longlines-mode` should use correct indentation for broken lines 640 641 * This is actually an enhancement of `longlines-mode` 642 643 * `longlines-mode` modifies the buffer 644 645 * This is needed to use all the standard functionality like 646 `move-to-column` 647 648 * Using property `display` for inserting indentation does not work 649 properly because of this 650 651 * Indentation must be inserted in the buffer 652 653 * However, it needs to have the property `intangible` so it can 654 not be modified 655 656 * See `Emacs Lisp => 32.19 Text Properties => Special 657 Properties` 658 659 * It would be nice to also have a visible indication for being 660 automatic insertion 661 662 * Such indentation must be removed by `longlines-encode-*` 663 664 * Probably it should be marked by a special property such as 665 `longlines-indentation` 666 667 * `longlines-wrap-line` needs a hook called after replacing the 668 blank by a soft newline 669 670 * May be `longlines-*search-*` needs to be adapted as well? 671 672Indent correctly 673================ 674 675* `rst-shift-region` should have a mode to indent correctly 676 677 * I.e.: Indent the region according to the tab given by the line 678 above 679 680* But see also `Copying literal blocks`_ 681 682Jumps leaving mark 683================== 684 685* All jumps across a wider distance should push the mark on the local 686 mark ring 687 688 * See C-u C-SPC documentation 689 690 * Jumps to section titles 691 692 * That would result in jumping back to TOC which is especially 693 useful for an internal TOC 694 695 * But not jumps to paragraphs 696 697 * Jumps with C-M-a / C-M-e? 698 699TOC controlling sliding window 700============================== 701 702* `toc-mode` must have a mode where cursor entering a new line moves 703 to the respective section in another window 704 705 * So one can browse through a buffer by using the TOC 706 707Jump to list entry on same level 708================================ 709 710* If on a list entry of some sort there should be a way to navigate to 711 a sibling 712 713 * Forward and backward 714 715* May be also up and down 716 717`rst-shift-region` shifts as needed 718=================================== 719 720* `rst-shift-region` should have an option to "do the right thing" 721 722* In particular it should shift as needed by the text above 723 724 * This makes indentation of an inserted block easier because you 725 don't need to know the correct number of tabs 726 727 * There should be an option to "align under", "align same" and 728 "align less" 729 730 * May be this could be commanded by one or more C-u's 731