Added Markdown support to wrap(1)

[Paul J. Lucas]

Hello -

I’ve been hacking on wrap(1) and wrapc(1) that are text and source-code-comment reformatters, respectively, for a long time. I started them to scratch my particular itch, namely the ability to easily rewrap text (and, in particular, comments in source code) while in an editor. See:

https://github.com/paul-j-lucas/wrap

The relevance for this mailing list is that I’ve recently completed adding Markdown support since source-code-comment-formatting tools like Doxygen now support Markdown. Unlike other Markdown formatters that convert Markdown into some other format (typically HTML), wrap does source-to-source reformatting, i.e., it rewraps Markdown text into nicer-looking Markdown text.

For example, if I had a Markdown comment like:

//
// While blank lines don't change state directly, we do have to keep track of
// when we've seen one because:
//
// + They help determine whether the line after the blank line is a
// continuation of the current state based on indentation.
// + They disambiguate "---" between a Setext 2nd-level header and a
// horizontal rule.
//

and then I edit the comment by inserting text into the second bullet:

//
// While blank lines don't change state directly, we do have to keep track of
// when we've seen one because:
//
// + They help determine whether the line after the blank line is a
// continuation of the current state based on indentation.
// + They disambiguate "---" between a Setext 2nd-level header (that has to have a text line before it) and a
// horizontal rule (that doesn't).
//

then the text of the bullet is too long. To make it look nice, ordinarily I’ve have to insert a newline, add another //, and join the second line of the bullet. Instead, while in vim (after having bound the key sequence `c for wrap comment), I can just type said sequence while the cursor is in that comment and it will instantly reformat the comment to:

//
// While blank lines don't change state directly, we do have to keep track of
// when we've seen one because:
//
// + They help determine whether the line after the blank line is a
// continuation of the current state based on indentation.
// + They disambiguate "---" between a Setext 2nd-level header (that
// has to have a text line before it) and a horizontal rule (that
// doesn't).
//

- Paul

[Marty McGowan]

paul,

being a bwk follower (the K in awk), i'm a fan of well-focused
tools; i suspect "wrap" is such.

however, wrapping is but a single feature in emacs. oh, if the world
had the patience to learn emacs.

and in a note of self-contradiction, it is a bit difficult to
reconcile heavy command-line use with such an editor.

i thank markdown for having lead me to OrgMode. and now my
command-line format converter is "pandoc". depending on the venue
(e.g. leanpub) it does a fine job of producing the necessary
markdown.

=*+*-
Marty McGowan 908 230-3739

Post by Paul J. Lucas
Hello -
I’ve been hacking on wrap(1) and wrapc(1) that are text and
source-code-comment reformatters, respectively, for a long time. I
started them to scratch my particular itch, namely the ability to easily
rewrap text (and, in particular, comments in source code) while in an
https://github.com/paul-j-lucas/wrap
_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

[Paul J. Lucas]

I'm really not sure what you're trying to say. Your mail seems to be all over the map.

This certainly isn't the forum for a vi vs. emacs war.

- Paul

Post by Marty McGowan
paul,
being a bwk follower (the K in awk), i'm a fan of well-focused
tools; i suspect "wrap" is such.
however, wrapping is but a single feature in emacs. oh, if the world
had the patience to learn emacs.
and in a note of self-contradiction, it is a bit difficult to
reconcile heavy command-line use with such an editor.
i thank markdown for having lead me to OrgMode. and now my
command-line format converter is "pandoc". depending on the venue
(e.g. leanpub) it does a fine job of producing the necessary
markdown.
=*+*-
Marty McGowan 908 230-3739

Post by Paul J. Lucas
Hello -
I’ve been hacking on wrap(1) and wrapc(1) that are text and
source-code-comment reformatters, respectively, for a long time. I
started them to scratch my particular itch, namely the ability to easily
rewrap text (and, in particular, comments in source code) while in an
https://github.com/paul-j-lucas/wrap
_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

[Sherwood Botsford]

He's made a plugin that reformats comments, and does The Right Thing with
MD within comments.

To me this is something that the text editor should do automatically.
This, and it's ilk, such as wrap, par, etc. have to be run as an external
command, piping out and in.

Respectfully,

Sherwood of Sherwood's Forests

Post by Paul J. Lucas
I'm really not sure what you're trying to say. Your mail seems to be all over the map.
This certainly isn't the forum for a vi vs. emacs war.
- Paul

Post by Marty McGowan
paul,
being a bwk follower (the K in awk), i'm a fan of well-focused
tools; i suspect "wrap" is such.
however, wrapping is but a single feature in emacs. oh, if the world
had the patience to learn emacs.
and in a note of self-contradiction, it is a bit difficult to
reconcile heavy command-line use with such an editor.
i thank markdown for having lead me to OrgMode. and now my
command-line format converter is "pandoc". depending on the venue
(e.g. leanpub) it does a fine job of producing the necessary
markdown.
=*+*-
Marty McGowan 908 230-3739

Post by Paul J. Lucas
Hello -
I’ve been hacking on wrap(1) and wrapc(1) that are text and
source-code-comment reformatters, respectively, for a long time. I
started them to scratch my particular itch, namely the ability to easily
rewrap text (and, in particular, comments in source code) while in an
https://github.com/paul-j-lucas/wrap
_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

[Paul J. Lucas]

He's made a plugin that reformats comments, and does The Right Thing with MD within comments.

And I presume it’s limited to emacs. If I wanted to use it for some other editor, or as part of another pipeline, or as part of a source code repository commit hook, I probably couldn’t use the plugin.

To me this is something that the text editor should do automatically. This, and it's ilk, such as wrap, par, etc. have to be run as an external command, piping out and in.

If you hadn’t seen some other editor, let’s call it, say, “iv” [sic] and I pre-configured it binding a certain key sequence to call an external command, and sat you down in front of it for you to use and didn’t tell you it used an external command, you wouldn’t know the difference.

You can’t be pointing out that it’s technically slightly less efficient because it has to spawn another process, I don’t think, because it’s all been completed by the time your fingers come completely off the keys. It is a text editor, after all, that spends most of its time waiting for a human to press keys. Efficiency at that level simply doesn’t matter.

If I had a Way-Back machine and release wrap with Markdown support before the emacs plugin, perhaps I could have commented, “If only people learned to write code the Unix way with pipes.” Nah, I wouldn’t do that. Why not? Because, as I stated initially, I started wrap in 1996 (!) to scratch my particular itch as someone who enjoys coding for its own sake. Perhaps Marty did something similar.

I announced wrap’s Markdown support on the list in case others might find it useful. If so, great; if not, just keep using what you’re using. There’s really no need for anything else.

- Paul

[Marty McGowan]

What attracted me to Markdown was it's underlying principle, that text
can be readable, and readily converted into formatted documents.

What lead me to Markdown took a few decades: I used a syntactic means to
format documents, developed while writing in nroff/troff at the turn of
the 70s/80s. I delivered a talk at the '82 Usenix "Make with M4".
What steered me to M4? That {nt}roff, in order to be useful, had a
macro facility. In my judgement, too easily confused with the Xroff
command language. So, "get yourself the equivalent functionality, that
when Xroff is superseded, you won't have to re-format all your papers in
the new language, simply cast the defining macros to emit the new stuff.
e.g.

_H( N, this is heading level N)

And this was a decade before I'd heard of HTML.

The two problem areas were m4's bindings with commas and parens, though
gnu m4 added some features to overcome those limitations, but the biggy
was the feature Markdown was best at: headers, paragraphs and lists. a
natural presentation with minimal noise.

So i give Markdown credit for putting me on the right path, and even
used it to publish my e-book: Shell Functions. Which I hope to update
soon. But now, I edit the text in emacs, OrgMode, and produce the
Leanpub/Markdown by using pandoc.

The thing i like about pandoc is it eliminates my need to anticipate the
next wave of document production: no need to upgrade 139 macro
definitions. Markdown had arrived just in the nick of time before I
was about to write the TeX productions.

The other thing pandoc has done for me is rescue my sister's
considerable effort in publishing the history pages of our family
genealogy (1400 people). The tree-portion she was able to export into
GEDCOM, and re-import to WikiTree; I've easily converted the narrative
portion to both a Markdown and an emacs OrgMode format. The question
remains, which of the available alternative formats (I'm thinking
Markdown) is most likely to be embraced by the next generation.

Pardon for taking valuable space, if not some of your time, on this
personal ramble. I believe it's useful to share why and how some of
our tools are begin used.

Cheers,

=*+*-
Marty McGowan 908 230-3739

He's made a plugin that reformats comments, and does The Right Thing with MD within comments.

... I started wrap in 1996 (!) to
scratch my particular itch as someone who enjoys coding for its own sake.
Perhaps Marty did something similar.
I announced wrap’s Markdown support on the list in case others might find
it useful. If so, great; if not, just keep using what you’re using.
There’s really no need for anything else.
- Paul
_______________________________________________
Markdown-Discuss mailing list
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss