I need to write code comments with aligned borders on all four sides due to an externally enforced coding standard.
What's the easiest way, in Emacs, to:
Convert some text into a block comment in this format
Edit the text in a block comment and have Emacs reflow it correctly
Comment format examples:
#*****************************************************************************#
#* This is a block comment. It has right-aligned borders. *#
#* *#
#* It can have separate paragraphs. Text in a long paragraph flows from one *#
#* line to the next with one space of internal padding. *#
#* *#
#* The right hand border is at char 78 *#
#*****************************************************************************#
sub MySub
{
#***************************************************************************#
#* The left hand edge of the comment is aligned with the current code *#
#* block, but the right hand border is still at char 78 *#
#***************************************************************************#
my $var = 3;
}
auto-fill-mode by itself doesn't preserve the right hand border.
The venerable and versatile library "rebox2" can do this.
To install, download https://raw.github.com/lewang/rebox2/master/rebox2.el into your site-lisp dir, and add the following to your .emacs file:
(require 'rebox2)
; The following template defines the specific style required here,
; which does not correspond to any built-in rebox2 style.
;
; "75" means that the style is registered as x75, where "x" depends
; on the current langauge mode. The "?" char is switched for the language
; specific comment char
;
; "999" is the weighting used for recognising this comment style.
; This value works for me.
(rebox-register-template
75
999
'("?*************?"
"?* box123456 *?"
"?*************?"))
(add-hook 'perl-mode-hook (lambda ()
; The "style loop" specifies a list of box styles which rebox will cycle
; through if you refill (M-q) a box repeatedly. Having "11" in this loop
; will allow you to easily "unbox" a comment block, e.g. for "uncomment-region"
(set (make-local-variable 'rebox-style-loop) '(75 11))
; The "min-fill-column" setting ensures that the box is not made narrower
; when the text is short
(set (make-local-variable 'rebox-min-fill-column) 79)
(rebox-mode 1)))
Now:
To convert some text into a block comment in this format, you just select the text and do M-q
To edit the text in a block comment, you can just edit the text directly, and emacs will reflow the box automatically. (You may need to do M-q to request a reflow if emacs doesn't automatically do it.)
M-x customize-variable RET comment-style RET
Then choose "box" from value-menue
You could use yasnippet for inserting and overwrite-mode for editing.
If you want word wrapping, you could also kill rectangle C-x r k,
switch to a temp buffer C-x b,
yank rectangle C-x r y. Edit there to your heart's content. Afterwards,
kill rectangle from the temp buffer and paste into your source.
Here's the block begin/end snippet:
# -*- mode: snippet -*-
# name: block comment
# key: bb
# --
`(concat "#" (make-string (- 80 aya-tab-position) ?*) "#")`
$0
`(concat "#" (make-string (- 80 aya-tab-position) ?*) "#")`
Here's the block line snippet:
# -*- mode: snippet -*-
# name: block comment line
# key: bl
# --
`"#* "`$1${1:$(make-string (- 78 aya-tab-position (length text)) ? )}#
Note that I'm using here the auto-yasnippet package variable aya-tab-position.
To use it in a snippet, you have to expand the snippet with aya-open-line.
You can get both packages from MELPA.
A partial answer to (1) (but I'd love to hear a better one):
Type the comment para as plain text
M-x set-fill-column 76
Place the cursor at the start of the comment para and manually typing in the opening "#* " (note space)
With the cursor at the first letter of the comment para, run M-x set-fill-prefix
Now use M-q to reflow the para
This will sort the word wrapping and put the left hand border in place.
Finally, manually add the top, bottom and right hand borders.
See http://www.gnu.org/software/emacs/manual/html_node/emacs/Fill-Prefix.html
The same approach can be used for some of (2):
Ensure that set-fill-column and set-fill-prefix are correct (see above)
Delete all the right hand border markers
Reflow the para using M-q
Finally, manually add the top, bottom and right hand borders.
Related
So in Emacs, word-wraping is called filling and is done by M-q or M-x fill-paragraph. Is there any way to modify this function to respect spaces that should be non-breaking? For example, if we have the following sentence:
This is a black sentence with a yellow word at the end.
and tell Emacs to fill-paragraph at mark 50, it wraps it like this:
This is a black sentence with a yellow word at the
end.
However, if I do the same with C-u M-x shell-command-on-region and enter fold -sw 50, I get the following (correct) output:
This is a black sentence with a yellow word at
the end.
A similar problem happens when the end of a sentence is followed by something in parentheses:
This is a black sentence with a yellow word here. (This is something in parens)
The above sentence is wrapped with M-q at mark 50 in the following way:
This is a black sentence with a yellow word
here. (This is something in parens)
However, fold -sw 50 wraps it correctly:
This is a black sentence with a yellow word here.
(This is something in parens)
I know I could just write a function that uses fold and use that but I'm curious as to why fill-paragraph behaves like this and if it can be modified.
I am not sure what your definition of "non-breaking" space is.
However, you can achieve what you want in your examples by doing:
(add-to-list 'fill-nobreak-predicate 'fill-single-word-nobreak-p)
(setq sentence-end-double-space nil)
Documentation (and comment) of fill-single-word-nobreak-p says:
"Don't break a line after the first or before the last word of a sentence."
;; Actually, allow breaking before the last word of a sentence, so long as
;; it's not the last word of the paragraph.
You can add your own predicates to the fill-nobreak-predicate list.
In text, can I make org-mode ignore forward slashes somehow? Phonetics uses /s/ to denote a certain level of analysis.
I assume that you do not want the text to appear emphasized in the buffer, nor in the output. This is a slightly more complex answer which will achieve that result:
There is a variable defined by Org-mode called org-emphasis-alist which defines the different emphasis modes, what their plain-text syntaxes are, and how they are exported to HTML. You can achieve the result you want by changing the value of this variable before Org-mode has been loaded. That last part is critical so note it well—Org-mode reads the value of org-emphasis-alist when it is loaded and uses that value to generate a regular expression for highlighting ("font-lock") purposes.
Here are two routes to that:
Add the following lines to your .emacs file above the lines that load Org-mode:
(setq org-emphasis-alist
`(("*" bold "<b>" "</b>")
;; ("/" italic "<i>" "</i>")
("_" underline "<span style=\"text-decoration:underline;\">" "</span>")
("=" org-code "<code>" "</code>" verbatim)
("~" org-verbatim "<code>" "</code>" verbatim)
("+" ,(if (featurep 'xemacs) 'org-table '(:strike-through t))
"<del>" "</del>")))
(Notice the commented out line.)
Make the change through Emacs' customization facility:
M-x customize RET
In the search box enter Org Emphasis and click Search.
Click the down arrow next to Org Emphasis Alist to reveal its value.
Find and click the second DEL button—corresponding to the italic list item.
Click the Save for future sessions button at the top of the buffer.
You can use
#+OPTIONS: *:nil
to turn off text-emphasis (bold,italics,underline). This will however only work on export itself, the emphasis will still be visible.
See the manual for other export options.
If you like the standard emphasis functionality of the forward slashes in org-mode, you could also just define a new environment. I put something like the following in the preamble whenever I do phonetics/phonology typesetting:
\newcommand\uRep[1]{$/$\textipa{#1}$/$}
Say I am in org-mode in a document with the following structure:
* First headline
* Second headline
** Section A
Here is one line
Here is another line
blah, blah
** Section B
Say the cursor is on the line that reads Here is another line. I would like to collapse ** Section A from this location with a keyboard shortcut.
If I press <TAB> it does not collapse ** Section A, as I would need the cursor to be on the stars for this to work.
If I press <Shift-TAB> it collapses all outlines, and not the current one.
Is there any way to cycle through the collapsing of the outline in scope (i.e. the "current outline")?
You can customize the behaviour of the org-cycle command (which is bound to <TAB>) by changing the value of org-cycle-emulate-tab.
To get it to collapse ** Section A when your cursor is on Here is another line add the following line to your .emacs file:
(setq org-cycle-emulate-tab 'white)
The white will allow you to still use <TAB> to indent in empty lines. From org-mode Github:
org-cycle-emulate-tab's value is t
Documentation:
Where should `org-cycle' emulate TAB.
nil Never
white Only in completely white lines
whitestart Only at the beginning of lines, before the first non-white char
t Everywhere except in headlines
exc-hl-bol Everywhere except at the start of a headline
If you don't mind doing this in two steps:
C-c C-p: move the cursor to the previous heading (** Section A in your example)
TAB: fold the section
This method doesn't require any configuration, as long as you get used to it.
How is automatic alignment of properties, in-buffer settings and similar things enabled?
I always end up with something like this and then have to align manually.
#+STARTUP: indent
#+PRIORITIES: A C B
#+COLUMNS: %ITEM %foo %bar
* section
:PROPERTIES:
:foo: foo
:barbaz: barbaz
:END:
However I found some signs alignment should happen automatically. E.g. there is this:
(defcustom org-property-format "%-10s %s"
"How property key/value pairs should be formatted by `indent-line'.
When `indent-line' hits a property definition, it will format the line
according to this format, mainly to make sure that the values are
lined-up with respect to each other."
:group 'org-properties
:type 'string)
Is there a command that will fixup a property to respect that? Shouldn't a property inserted with org-set-property follow that format? M-x org-indent-line doesn't do anything for me and indent-line doesn't exist.
org-indent-line did not do the right thing when the property keyword was right at the beginning of the line. It does now.
Also, from a fresh git pull, using C-M-\ on the region will indent the region.
To format the options header you can select the region you want to align and do
M-x align-regexp RET <space> RET
How can I make Emacs automatically wrap lines of text that I've already written such that no line is longer than, say, 70 characters. In other words, I'd like to do "auto-fill-mode" after-the-fact.
Is this possible?
Look at fill-paragraph and fill-region. If I remember correctly, it's bound to M-q by default. To set the line width, use C-xf.
In addition to fill-paragraph and fill-region, take a look at these commands:
file-individual-paragraphs: "Fill paragraphs of uniform indentation within the region.
This command divides the region into "paragraphs",
treating every change in indentation level or prefix as a paragraph boundary,
then fills each paragraph using its indentation level as the fill prefix.
There is one special case where a change in indentation does not start
a new paragraph. This is for text of this form:
foo> This line with extra indentation starts
foo> a paragraph that continues on more lines.
These lines are filled together."
fill-nonuniform-paragraphs: "Fill paragraphs within the region, allowing varying indentation within each.
This command divides the region into "paragraphs",
only at paragraph-separator lines, then fills each paragraph
using as the fill prefix the smallest indentation of any line
in the paragraph."