markdown?

[Jonathan Rochkind]

I just had a crazy idea, put it out there for discussion, certainly not expecting any immediate action, even if people like it we'll want to stew on it for a while.

One of the most time consuming and annoying parts of editing the journal is getting things into HTML and editing the HTML without WordPress messing it up, etc.

Lately I've been using various "mostly plaintext but with conventions that can be formatted into html" formats, such as [markdown](http://daringfireball.net/projects/markdown/syntax), [textile](http://daringfireball.net/projects/markdown/syntax), and a few others. They are SO much easier to use. markdown is the most popular.

There are some markdown plugins for WP.

* What if we required authors to submit in markdown (basically plaintext with some pretty easy to remember conventions for indicating headers, lists, links, embedded images, etc)
* Then we just entered the markdown in WordPress
* Profit!

## Disadvantages

* We wouldn't be able to use fancy custom HTML anymore. This has some pro's in enforcing consistency, but also some obvious cons.
* We'd probably have to give up on the COinS, which I think would actually be fine. Some years on, COinS has not really caught on, I'm not sure it provides a benefit commensurate to the effort it takes us, and we usually don't manage to do it right anyway. Few of our articles include links to non-open-access literature anyway.
* On the other hand, we can't give up code syntax highlighting. Not sure if WP markdown plugins would play nice with the syntax highlighter plugin, but they might.
* We'd have to figure out how to conveniently do notes/references too, especially for articles that want the (Smith 2000) style to be most readable.
* Not sure how we'd get things like our formatted captions on figures to work right, or center-aligned figures, etc.

So there'd be some challenges. But I suspect they could be overcome. And I think it would make our jobs so much easier, take out the most annoying and least rewarding thing editors spend time on. And, hey, forcing the limitation to the subset of HTML that markdown can represent would make an article-to-PDF converter a lot easier too.

## Note

This email is, as you may have guessed, in markdown.

[Tom Keays]

Markdown was one of the first text syntaxes I used (in a Moveable Type blog I had 8 or so years ago) and it is still a fine markup language. I think it _can_ coexist with raw HTML (at least my Moveable Type blog could, through a post-specific setting), but probably not with the WYSIWYG editor. Something to keep in mind.

Barring technical complications, however, one concern might be people's comfort level using the markup syntax approach. That seems to be the crux of people's resistance to using wikis. How much of a problem will editors find it to convert a formatted word processing document to Markdown?

Another concern is the ability to track changes. One of the articles I edited this year was originally submitted in a text markup syntax (Textile, I think). I eventually converted it to Word and coordinated further edits with the authors that way. If we had a way to track changes and share them with the authors using Wordpress, that would have addressed that problem very nicely. This is true regardless of whether we decide to go with Markdown or not. Our current editing paradigm is not to enter the article into Wordpress until most of the changes have been made, which mitigates the problem somewhat.

These are devil's advocate objections though. If others like the idea, we should definitely explore it.

Tom

--
You received this message because you are subscribed to the Google Groups "Code4Lib Journal-discuss" group.
To post to this group, send email to c4lj-d...@googlegroups.com.
To unsubscribe from this group, send email to c4lj-discuss...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/c4lj-discuss?hl=en.

[Jonathan Rochkind]

Yeah, track changes, I dunno. I don't like our current 'solution' for track changes, passing around Word documents, but don't know of a better solution, markdown or not. (And we don't require authors to submit in Word or be able to open a Word file now, in fact).

I wonder if there's a WordPress plugin that puts your posts in a code versioning system of some kind and lets you look at histories/diffs? Maybe that'd be the solution there -- which WOULD work better with markdown. With HTML, you're likely to get a lot of diffs that are just fixes to HTML syntax and structure and formatting rather than actual content.

Markdown (or textile) are SO easy to use, that I personally don't see a problem with requiring authors to use it. We are a technical journal after all. (It looks like there may be some textile WP plugins too, so it could be textile instead of markdown. Depends on if ANY of these plugins, textile or markdown, are stable, mature, and flexible/powerful enough for our use, which I'm not sure).

But I'm not looking for any immediate action on this, it's really just food for thought. I'd like to come up with SOME better way of handling our workflow. (While still being focused on HTML as our primary delivery, not PDF. When I think 'troubles with workflow', I think , gee, let's see what OJS does -- but they seem to punt on HTML entry/editing workflow problems, instead focusing on PDFs as the primary delivery. Which is not where any of us want to go.)

________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Tom Keays [tomk...@gmail.com]
Sent: Thursday, July 21, 2011 9:52 PM
To: c4lj-d...@googlegroups.com
Subject: Re: [c4lj] markdown?

Markdown was one of the first text syntaxes I used (in a Moveable Type blog I had 8 or so years ago) and it is still a fine markup language. I think it _can_ coexist with raw HTML (at least my Moveable Type blog could, through a post-specific setting), but probably not with the WYSIWYG editor. Something to keep in mind.

Barring technical complications, however, one concern might be people's comfort level using the markup syntax approach. That seems to be the crux of people's resistance to using wikis. How much of a problem will editors find it to convert a formatted word processing document to Markdown?

Another concern is the ability to track changes. One of the articles I edited this year was originally submitted in a text markup syntax (Textile, I think). I eventually converted it to Word and coordinated further edits with the authors that way. If we had a way to track changes and share them with the authors using Wordpress, that would have addressed that problem very nicely. This is true regardless of whether we decide to go with Markdown or not. Our current editing paradigm is not to enter the article into Wordpress until most of the changes have been made, which mitigates the problem somewhat.

These are devil's advocate objections though. If others like the idea, we should definitely explore it.

Tom

On Thu, Jul 21, 2011 at 8:19 PM, Jonathan Rochkind <roch...@jhu.edu<mailto:roch...@jhu.edu>> wrote:
I just had a crazy idea, put it out there for discussion, certainly not expecting any immediate action, even if people like it we'll want to stew on it for a while.

One of the most time consuming and annoying parts of editing the journal is getting things into HTML and editing the HTML without WordPress messing it up, etc.

Lately I've been using various "mostly plaintext but with conventions that can be formatted into html" formats, such as [markdown](http://daringfireball.net/projects/markdown/syntax), [textile](http://daringfireball.net/projects/markdown/syntax), and a few others. They are SO much easier to use. markdown is the most popular.

There are some markdown plugins for WP.

* What if we required authors to submit in markdown (basically plaintext with some pretty easy to remember conventions for indicating headers, lists, links, embedded images, etc)
* Then we just entered the markdown in WordPress
* Profit!

## Disadvantages

* We wouldn't be able to use fancy custom HTML anymore. This has some pro's in enforcing consistency, but also some obvious cons.
* We'd probably have to give up on the COinS, which I think would actually be fine. Some years on, COinS has not really caught on, I'm not sure it provides a benefit commensurate to the effort it takes us, and we usually don't manage to do it right anyway. Few of our articles include links to non-open-access literature anyway.
* On the other hand, we can't give up code syntax highlighting. Not sure if WP markdown plugins would play nice with the syntax highlighter plugin, but they might.
* We'd have to figure out how to conveniently do notes/references too, especially for articles that want the (Smith 2000) style to be most readable.
* Not sure how we'd get things like our formatted captions on figures to work right, or center-aligned figures, etc.

So there'd be some challenges. But I suspect they could be overcome. And I think it would make our jobs so much easier, take out the most annoying and least rewarding thing editors spend time on. And, hey, forcing the limitation to the subset of HTML that markdown can represent would make an article-to-PDF converter a lot easier too.

## Note

This email is, as you may have guessed, in markdown.

--
You received this message because you are subscribed to the Google Groups "Code4Lib Journal-discuss" group.

To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.
To unsubscribe from this group, send email to c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com>.

[Kelley McGrath]

One thing I like about C4LJ is the low barrier for entry for authors
to get their content out. Even though this might not be all that hard
to do, it potentially takes authors out of their normal writing
workflow. Authors may also have already written something up in
another format before deciding to submit to us. I think there are some
parallels with the citation format discussion. I could go for an
option or suggestion, but don't think I'd like to see it made a
requirement.

Kelley

[Jonathan Rochkind]

Well, even if we allow authors to submit however they want, I suppose we could copy and paste as PLAIN TEXT (rather than HTML) and apply markdown/textile ourselves, which I think would still be a lot less annoying work than trying to get it entered in into WP in HTML.
________________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Kelley McGrath [kmc...@gmail.com]
Sent: Friday, July 22, 2011 12:21 PM

[Tom Keays]

On Fri, Jul 22, 2011 at 11:34 AM, Jonathan Rochkind <roch...@jhu.edu> wrote:

Yeah, track changes, I dunno. I don't like our current 'solution' for track changes, passing around Word documents, but don't know of a better solution, markdown or not. (And we don't require authors to submit in Word or be able to open a Word file now, in fact).

Wordpress itself keeps a version history for each article, but it isn't a track changes system by any means. Plus, only the editors can see the versions; we can't share them with the authors in the current set up.

One thing that occurred to me awhile back is that we could set up a separate private Wordpress instance where article drafts are composed and edited. In this scenario, (regardless of whether we settle on a Markdown plugin approach or not) the Wordpress instance would be enabled with the DigressIt plugin [1] (the successor to CommentPress [2]) which would allow editors and authors to comment, section by section, on passages in the article. Depending on how it was set up, it could even allow authors and editors to collaboratively edit the article itself. This doesn't really address Kelley's concern about not taking "authors out of their normal writing workflow" though. I'm also not sure what happens to the section comments if you move sections around in the posting; it was a problem in CommentPress, I know.

Another problem, and the main reason I haven't proposed the idea before, is DigressIt treats individual posts as chapters in a single work ("work" here being the entire blog; see some of the examples [3]). Because it indexes posts as they're published, there's no real way to keep articles private from anyone who has access to this editing area. Authors could see all the articles underway, even articles that might not end up being published. That would be awkward, at the very least. 

However, in our current scenario, draft articles in Wordpress are not indexed and are not viewable unless you have logged in (authors are given a read-only login for this purpose). That approach might work in a DigressIt powered system too but I haven't played around with it enough to conceptualize it further.

[1] http://digress.it/
[2] http://www.futureofthebook.org/commentpress/
[3] http://digress.it/examples/

Another approach entirely might be just to compose and edit the draft articles in a wiki -- ideally using the same markup syntax that the Wordpress blog uses. Wikis generally have robust versioning systems built-in, but tracking changes in a given passage is still a tedious, iterative process -- you have to step through all the various versions until you see the change appear.

Tom

[Jonathan Rochkind]

We could also give each author their own login (rather than the shared login) earlier in the process, and give them access to their draft article (but not other articles), if that would help with any of these ideas, and if it's easy to do in WP, which I think it should be.

________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Tom Keays [tomk...@gmail.com]

Sent: Friday, July 22, 2011 12:32 PM

To: c4lj-d...@googlegroups.com
Subject: Re: [c4lj] markdown?

Tom

[Tom Keays]

On Fri, Jul 22, 2011 at 12:31 PM, Jonathan Rochkind <roch...@jhu.edu> wrote:

Well, even if we allow authors to submit however they want, I suppose we could copy and paste as PLAIN TEXT (rather than HTML)  and apply markdown/textile ourselves, which I think would still be a lot less annoying work than trying to get it entered in into WP in HTML

FWIW, I already do that anyway. Because I use the HTML editor (not the WYSIWYG editor), I actually do my edits in a separate text file and upload them to Wordpress as I go along. The main worry here is that another editor will fix something and I'll come along unknowing and undo it.

Tom

[Jonathan Rochkind]

Yeah, wouldn't fix that problem, but for me at least it would make it easier for me to be doing my conversion/edits in markdown instead of HTML.

________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Tom Keays [tomk...@gmail.com]

Sent: Friday, July 22, 2011 12:35 PM

To: c4lj-d...@googlegroups.com
Subject: Re: [c4lj] markdown?

Tom

--

[Kelley McGrath]

I have actually been pretty happy with the copy from Word plug-in,
although it may be that I may have articles with less complicated
layout issues and I am certainly a less discerning consumer of HTML.

Kelley

[Gabriel Farrell]

On Fri, Jul 22, 2011 at 11:34 AM, Jonathan Rochkind <roch...@jhu.edu> wrote:
> Yeah, track changes, I dunno. I don't like our current 'solution' for track changes, passing around Word documents, but don't know of a better solution, markdown or not. (And we don't require authors to submit in Word or be able to open a Word file now, in fact).
>
> I wonder if there's a WordPress plugin that puts your posts in a code versioning system of some kind and lets you look at histories/diffs? Maybe that'd be the solution there -- which WOULD work better with markdown. With HTML, you're likely to get a lot of diffs that are just fixes to HTML syntax and structure and formatting rather than actual content.

The article I edited for issue 13 (From ISIS to CouchDB) was handled
in a DVCS (Mercurial, hosted at bitbucket.org, because that's where
Luciano had it set up). I must say, it made for a great workflow that
I would love to repeat. Not all authors would be comfortable working
in version control, and I appreciate our flexibility in handling
whatever the author brings to us, but my ideal would be Markdown
articles in a Git repo. Could we at least encourage that somehow?

[Jodi Schneider]

That's really interesting, Gabe. How did you handle comments and suggestions?

It would be useful to see this repository if it's public, to get ideas.

-Jodi

[Gabriel Farrell]

On Sun, Jul 24, 2011 at 11:06 AM, Jodi Schneider <jschn...@pobox.com> wrote:
> That's really interesting, Gabe. How did you handle comments and
> suggestions?

I think we just handled larger editorial suggestions via email, though
I could see using issues or commit comments for that purpose. That's
assuming the use of Github -- we could use another ticketing/issue
system as well.

> It would be useful to see this repository if it's public, to get ideas.

https://bitbucket.org/gsf/papers

[Jodi Schneider]

On Sun, Jul 24, 2011 at 6:06 PM, Gabriel Farrell <gsf...@gmail.com> wrote:

On Sun, Jul 24, 2011 at 11:06 AM, Jodi Schneider <jschn...@pobox.com> wrote:
> That's really interesting, Gabe. How did you handle comments and
> suggestions?

I think we just handled larger editorial suggestions via email, though
I could see using issues or commit comments for that purpose. That's
assuming the use of Github -- we could use another ticketing/issue
system as well.

> It would be useful to see this repository if it's public, to get ideas.

https://bitbucket.org/gsf/papers

Thanks!

[Jonathan Rochkind]

Hmm, one road block is that I think most authors wouldn't want their initial drafts -- and especially comments/revisions back and forth between editors and author -- to be public.

I'm not sure if there's a free/cheap revision control system that also has a good web interface including editing text in a browser. Otherwise it's an interesting idea. I haven't looked at Mecurial/bitbucket, but Github gives you an in browser 'edit' button (just an HTML text box, no graphical wysiwyg or anything), and also renders markdown (or textile, or a couple others) after you save, in the browser. You wouldn't even have to know you were using a revision control system. But it'd be public.

________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Jodi Schneider [jschn...@pobox.com]
Sent: Sunday, July 24, 2011 2:33 PM

To: c4lj-d...@googlegroups.com
Subject: Re: [c4lj] markdown?

On Sun, Jul 24, 2011 at 6:06 PM, Gabriel Farrell <gsf...@gmail.com<mailto:gsf...@gmail.com>> wrote:

On Sun, Jul 24, 2011 at 11:06 AM, Jodi Schneider <jschn...@pobox.com<mailto:jschn...@pobox.com>> wrote:
> That's really interesting, Gabe. How did you handle comments and
> suggestions?

I think we just handled larger editorial suggestions via email, though
I could see using issues or commit comments for that purpose. That's
assuming the use of Github -- we could use another ticketing/issue
system as well.

> It would be useful to see this repository if it's public, to get ideas.

https://bitbucket.org/gsf/papers

Thanks!

> -Jodi
>
> On Sun, Jul 24, 2011 at 3:37 PM, Gabriel Farrell <gsf...@gmail.com<mailto:gsf...@gmail.com>> wrote:
>>
>> On Fri, Jul 22, 2011 at 11:34 AM, Jonathan Rochkind <roch...@jhu.edu<mailto:roch...@jhu.edu>>

>> wrote:
>> > Yeah, track changes, I dunno. I don't like our current 'solution' for
>> > track changes, passing around Word documents, but don't know of a better
>> > solution, markdown or not. (And we don't require authors to submit in Word
>> > or be able to open a Word file now, in fact).
>> >
>> > I wonder if there's a WordPress plugin that puts your posts in a code
>> > versioning system of some kind and lets you look at histories/diffs? Maybe
>> > that'd be the solution there -- which WOULD work better with markdown. With
>> > HTML, you're likely to get a lot of diffs that are just fixes to HTML syntax
>> > and structure and formatting rather than actual content.
>>
>> The article I edited for issue 13 (From ISIS to CouchDB) was handled

>> in a DVCS (Mercurial, hosted at bitbucket.org<http://bitbucket.org>, because that's where

>> Luciano had it set up). I must say, it made for a great workflow that
>> I would love to repeat. Not all authors would be comfortable working
>> in version control, and I appreciate our flexibility in handling
>> whatever the author brings to us, but my ideal would be Markdown
>> articles in a Git repo. Could we at least encourage that somehow?
>>
>> > Markdown (or textile) are SO easy to use, that I personally don't see a
>> > problem with requiring authors to use it. We are a technical journal after
>> > all. (It looks like there may be some textile WP plugins too, so it could be
>> > textile instead of markdown. Depends on if ANY of these plugins, textile or
>> > markdown, are stable, mature, and flexible/powerful enough for our use,
>> > which I'm not sure).
>> >
>> > But I'm not looking for any immediate action on this, it's really just
>> > food for thought. I'd like to come up with SOME better way of handling our
>> > workflow. (While still being focused on HTML as our primary delivery, not
>> > PDF. When I think 'troubles with workflow', I think , gee, let's see what
>> > OJS does -- but they seem to punt on HTML entry/editing workflow problems,
>> > instead focusing on PDFs as the primary delivery. Which is not where any of
>> > us want to go.)
>> >
>> > ________________________________

>> > From: c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com> [c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>] on
>> > behalf of Tom Keays [tomk...@gmail.com<mailto:tomk...@gmail.com>]

>> > Sent: Thursday, July 21, 2011 9:52 PM

>> > To: c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>

>> > c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com><mailto:c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>>.

>> > To unsubscribe from this group, send email to

>> > c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com><mailto:c4lj-discuss%2Bunsu...@googlegroups.com<mailto:c4lj-discuss%252Buns...@googlegroups.com>>.

>> > For more options, visit this group at
>> > http://groups.google.com/group/c4lj-discuss?hl=en.
>> >
>> >
>> >
>> > --
>> > You received this message because you are subscribed to the Google
>> > Groups "Code4Lib Journal-discuss" group.

>> > To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.

>> > To unsubscribe from this group, send email to
>> > c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com>.
>> > For more options, visit this group at
>> > http://groups.google.com/group/c4lj-discuss?hl=en.
>> >
>> > --
>> > You received this message because you are subscribed to the Google
>> > Groups "Code4Lib Journal-discuss" group.

>> > To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.

>> > To unsubscribe from this group, send email to
>> > c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com>.
>> > For more options, visit this group at
>> > http://groups.google.com/group/c4lj-discuss?hl=en.
>> >
>> >
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "Code4Lib Journal-discuss" group.

>> To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.

>> To unsubscribe from this group, send email to
>> c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com>.
>> For more options, visit this group at
>> http://groups.google.com/group/c4lj-discuss?hl=en.
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Code4Lib Journal-discuss" group.

> To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.

> To unsubscribe from this group, send email to
> c4lj-discuss...@googlegroups.com<mailto:c4lj-discuss%2Bunsu...@googlegroups.com>.
> For more options, visit this group at
> http://groups.google.com/group/c4lj-discuss?hl=en.
>

--
You received this message because you are subscribed to the Google Groups "Code4Lib Journal-discuss" group.

To post to this group, send email to c4lj-d...@googlegroups.com<mailto:c4lj-d...@googlegroups.com>.

[Tom Keays]

That's an interesting approach and one I could see working with our current workflow. It does mean manually updating Wordpress when edits are accepted, but that's not really a big problem. I like the idea of being able to share it with the authors.

Can you clarify: you would recommend Github over Bitbucket for this purpose because it handles commenting better?

Also, I noticed that all the text was hard-wrapped to 80 characters. Is line wrapping required or just your preference? When I have edited my articles in a text editor, I only put hard returns at the end of paragraphs.

Tom

[Tom Keays]

GitHub has a new GUI editing client for the Macintosh. Requires Snow Leopard (10.6) or higher.
http://mac.github.com/

Windows and Linux still have command driven interfaces, but they're really not too bad. E.G.,
http://help.github.com/win-set-up-git/
http://help.github.com/linux-set-up-git/

Tom

[Tim McGeary]

This is a very interesting thread. I think I've now edited articles in
4 different ways:

* traditional MS-Word w/ Track Changes
* Open Office Word w/ highlighted changes and comments
* Google Docs with editing privileges shared by the author
* Rich Text File, which I copied into MS-Word, edited via Track Changes,
and then saved to PDF to send back to author

I. myself, don't feel inconvenienced by another of those paths, and I've
only had minor problems copy/pasting into the Visual tab of WordPress.

I have the hardest time getting images and code snipped in and formatted
properly to fit.

Otherwise, I'm inclined to say the process isn't broken, so why fix it.
But I won't stand opposed to more efficiencies.

Tim M

> <roch...@jhu.edu <mailto:roch...@jhu.edu>>

> >> wrote:
> >> > Yeah, track changes, I dunno. I don't like our current
> 'solution' for
> >> > track changes, passing around Word documents, but don't know
> of a better
> >> > solution, markdown or not. (And we don't require authors to
> submit in Word
> >> > or be able to open a Word file now, in fact).
> >> >
> >> > I wonder if there's a WordPress plugin that puts your posts in
> a code
> >> > versioning system of some kind and lets you look at
> histories/diffs? Maybe
> >> > that'd be the solution there -- which WOULD work better with
> markdown. With
> >> > HTML, you're likely to get a lot of diffs that are just fixes
> to HTML syntax
> >> > and structure and formatting rather than actual content.
> >>
> >> The article I edited for issue 13 (From ISIS to CouchDB) was handled
> >> in a DVCS (Mercurial, hosted at bitbucket.org

> <http://bitbucket.org>, because that's where

> <mailto:c4lj-d...@googlegroups.com>
> [c4lj-d...@googlegroups.com
> <mailto:c4lj-d...@googlegroups.com>] on

> >> > behalf of Tom Keays [tomk...@gmail.com

> <mailto:tomk...@gmail.com>]

> >> > Sent: Thursday, July 21, 2011 9:52 PM
> >> > To: c4lj-d...@googlegroups.com

> <mailto:c4lj-d...@googlegroups.com>

> <mailto:roch...@jhu.edu><mailto:roch...@jhu.edu

> <mailto:c4lj-d...@googlegroups.com><mailto:c4lj-d...@googlegroups.com

> <mailto:c4lj-d...@googlegroups.com>>.
> >> > To unsubscribe from this group, send email to
> >> > c4lj-discuss...@googlegroups.com

> <mailto:c4lj-discuss%2Bunsu...@googlegroups.com><mailto:c4lj-discuss%2Bunsu...@googlegroups.com
> <mailto:c4lj-discuss%252Buns...@googlegroups.com>>.

> To post to this group, send email to c4lj-d...@googlegroups.com

[Jonathan Rochkind]

We're obviously not going to be able to require that all authors/editors have OSX.

But what I was thinking was that if we used github (which I'm still not entirely sold on), some people could get by with just the github _web_ interface, which is available to everyone. github (a particular git host, with their own web interface) lets you edit text through the web, look at diffs and commit histories, and it renders markdown and textile too.  If we were going to use github for workflow, I think we'd have to come up with a workflow so that the functions avaialble through the web interface are sufficient for the authors end of workflow, and ideally for the editors as well. (I don't know if you can merge/pull through the web interface).

[Jonathan Rochkind]

I wonder what the HTML source looks like for everyone that thinks they
have had no problems copying/pasting from WordPress to Word. I'm
thinking there's a good chance it's pretty awful, with extra divs and
spans all over the place, "font" tags, possibly "font" tags instead of
headers, etc.

It might be painful for me because I try to avoid this and have good HTML.

Does this matter, ugly HTML? I am not sure; terrible HTML will
certainly make an attempt at converting to PDF much harder; my intutions
as a programmer is that it will make other unexpected things we want to
do later harder too, but maybe caring about good HTML is just a
programmer being anal and not really neccesary.

Jonathan

[Kelley McGrath]

Have you tried the copy from Word plug-in? It might not be perfect,
but it's nothing like the native HTML output from Word.

[Gabriel Farrell]

On Mon, Jul 25, 2011 at 9:32 AM, Tom Keays <tomk...@gmail.com> wrote:
> That's an interesting approach and one I could see working with our current
> workflow. It does mean manually updating Wordpress when edits are accepted,
> but that's not really a big problem. I like the idea of being able to share
> it with the authors.
>
> Can you clarify: you would recommend Github over Bitbucket for this purpose
> because it handles commenting better?

Github is generally better than Bitbucket -- cleaner interface, more
features, bigger community, more ongoing development, etc.

> Also, I noticed that all the text was hard-wrapped to 80 characters. Is line
> wrapping required or just your preference? When I have edited my articles in
> a text editor, I only put hard returns at the end of paragraphs.

Both Luciano and I were used to hard-wrapped text. It's easier to edit
in Vim, and line-by-line changes are easier to track in a diff. You
can see in the repo that he even wrote a small script to unwrap the
text for WordPress, since it likes to insert a <br> whenever it's
given the opportunity (a minor annoyance).

[Tom Keays]

That would definitely work for us. Thanks for the explanation.
Tom

[Tod Olson]

Tim pretty much sums up my feelings on the topic.

-Tod

Tod Olson <t...@uchicago.edu>
Systems Librarian
University of Chicago Library

[Gabriel Farrell]

I agree with Tim as well. While I tend to encourage authors away from
Word, since I usually work on computers without Word installed, I'm
happy to accommodate various formats and workflows. Keeps things
interesting.

Going forward, I'll probably suggest Github, and if the author is
comfortable with version control, plain text, and public drafts, then
great. If not, no biggie.

If we could allow for Markdown input in addition to our current
methods, I'd be in favor of that.

[Jonathan Rochkind]

Yep, I have.

[Tom Keays]

I'm going to try this out...

Qute for PC/Mac is a text editor with Markdown and TeX support. Qute offers per paragraph preview, i.e., users can switch between editing the source and viewing a rich text rendering with typeset formulas for each paragraph separately.

http://www.inkcode.net/qute

[Tom Keays]

Qute is a nice and simple editor. By default, it displays the markdown text in the rich format view. You click a paragraph to go into text edit mode and when you are done, double-click to leave edit mode. Multiple paragraphs can be in edit mode simultaneously.

You can export the text to HTML and it seems pretty clean (I used their example text, so I didn't test it too hard yet). Headings are automatically marked with an ID attribute.

Editing mathematical formulas can also be accommodated. Because Qute includes MathJax rendering of LaTeX, we could avoid the use of embedded image files to represent these formulas.

Even if we didn't take the approach of installing a Markdown plugin in Wordpress, the Qute editor would let us still use Markdown in the editing process and then export HTML to place into Wordpress. The scenario of doing version control and collaborative editing in GitHub that Gabe described could also be accommodated using this editing environment.

If any of the editors end up pursuing this approach, please let the rest of us know how well it worked.

Tom

[Tom Keays]

My main criticisms of Qute so far are UI-related, at least on the Macintosh. I'll have to try it on my Windows machine tomorrow to see how it compares.

1. You can't open a file directly in Qute. You first have to start the program and then open the program from the options menu. Clunky.
2. Given the criticism of #1, it doesn't remember the last file you opened. It always opens a default page of Qute editing tips. There's no way to change this I can see.
3. It doesn't any Markdown syntax hints. Even the Markdown bundle for TextMate does this. On the plus side, there's good help/hints on the program's keyboard option.
4. Limited font and theme options. Some of them are quite unusable.
5. You can only edit one document at a time.
6. No quit option. Closing the window closes the program. Very unMac-like UI.

The LaTeX rendering via MathJax, on the other hand, rocks. It isn't a LaTeX editor by any means. (For that, I'd probably use this online equation editor: http://www.codecogs.com/latex/eqneditor.php and import the equations from there.) But once you've worked out the LaTeX, it is easy to export the Javascript/HTML for use in Wordpress. This might be moot if we use a MathJax Wordpress plugin to do that work.

But, for a 0.3 beta, I'm think it does a good job for most things.

Tom

[Gabriel Farrell]

Thanks for looking into this, Tom. Sounds like Qute could be useful
for converting Markdown to HTML, but that can also be done with the
original Markdown.pl script. I think I'd prefer a conversion step to
learning a new editor (I admit my Vim addiction).

I also still like the idea of a plugin so we can just enter the
Markdown text into WordPress directly. Looking around, though, there's
no clear winner in that arena, and the options all seem a bit hairy.
I'd be happy to help you test them out, though.

[Jonathan Rochkind]

Yeah, I don't really like adding another step or tool into our workflow, the idea of markdown appealed to me only with a plugin that supported it in wordpress. If that's not feasible, I think it might just make our workflow more complicated, rather than the desired goal of simpler.
________________________________________
From: c4lj-d...@googlegroups.com [c4lj-d...@googlegroups.com] on behalf of Gabriel Farrell [gsf...@gmail.com]
Sent: Thursday, August 11, 2011 10:06 AM
To: c4lj-d...@googlegroups.com
Subject: Re: [c4lj] markdown?

Thanks for looking into this, Tom. Sounds like Qute could be useful

[Gabriel Farrell]

I like the looks of markItUp! (http://markitup.jaysalvat.com/), in
that it might allow more flexibility in our input formats. Looking
over the docs it's still not clear to me how easy it would be to
switch between Markdown and HTML editing, though. I assume we'd always
want access to the raw HTML to make sure the output is correct. Might
be worth testing.

[Tom Keays]

MarkItUp looks pretty good as a standalone, web-based editor. 

I downloaded the code base and the additional markdown set of json and css config files. However, it appears that, in addition, the Markdown need to be parsed using a perl or php parser. Maybe I'll pursue that out of curiousity, but the end result would be a web page with a Markdown editing box, such as the MarkItUp demo area provides:

  http://markitup.jaysalvat.com/examples/markdown/

There is a MarkItUp plugin for Wordpress

  http://wordpress.org/extend/plugins/wp-markitup/

however it hasn't been been updated since 2009; compatible, therefore only up to Wordpress 2.7. The author's project link

  http://www.stefanoverna.com/projects/wp_markitup

also seems to be gone, so this makes this plugin a little dicey for us to consider. If the plugin itself had been up to date, it might have made sense to take the extra steps to implement Markdown within it.

Anyway, that puts us back to Jonathan's original suggestion to implement a Markdown plugin in Wordpress. There are a number of examples on the Wordpress codex site

  http://wordpress.org/extend/plugins/tags/markdown

but "Markdown on Save" sounds, at first glance, to be the most viable

  http://wordpress.org/extend/plugins/markdown-on-save/

It doesn't have a replacement editor box, like the MarkItUp plugin offered, so you have to insert the Markdown syntax yourself -- that's not that big a deal to learn. One of the things we talked about in this thread was how to prevent messing up previous article formatting and, by extension, what to do if a given editor would prefer not to use Markdown. Here's the blurb from the project page:

This plugin allows you to compose content in Markdown on a per-item basis. The markdown version is stored separately (in the post_content_formatted column), so you can deactivate this plugin and your posts won't spew out Markdown, because HTML is stored in the post_content, just like normal. This is also much faster than doing on-the-fly Markdown conversion on every page load. It's only done once! When you re-edit the post, the markdown version is swapped into the editor for you to edit. If something external updates the post content, you'll lose the Markdown version.

I'll test this out and see how it works. 

Back to Qute: I downloaded it on my Windows machine at work. The verdict: essentially identical to the Mac version -- functional but clunky UI. It's nice to see Markdown displayed in a rich view so easily, but it probably doesn't solve our problem. 

Tom

[Jonathan Rochkind]

Yep, that plugin seemed the best to me when I was looking around too – I really like it’s design, with the separate “post_content_formatted column”, such that you can de-activate it later and you’ve still got HTML for ordinary wordpress.  That’s definitely the right way to do it, keeping us from getting locked in.

 

If we decided we liked the idea of markdown (and this is still just an investigative experiment right now, there isn’t necessarily consensus), I think it would be fine to simply disable the “visual editor”, and have everyone write markdown. (the visual editor is, I think, a cause of terrible HTML output in our present setup).

 

If “markdown on save” hasn’t been updated or doesn’t work well with modern versions of WP… maybe one of us or a volunteer would be interested in updating/maintaining it, ha.  Or maybe not.  This is just exploratory investigation at this point!

 

One problem with this markdown approach is that people have generally said they would NOT want to make authors submit in markdown and WOULD like to keep accepting in MS Word (which they like for it’s track changes).  And some editors have said that they DO like the WordPress Word->HTML converter.  Which if we were doing all markdown, wouldn’t be available anymore. So that could be a roadblock. On the other hand “markdown on save” would let SOME articles be input HTML and others in Markdown – but I worry that having that kind of a mixed environment again is just making our infrastructure _more_ complicated, when the goal is simplifying it. (For instance, if everything was in markdown, a PDF output converter would be a lot easier. If some things were in html and others in markdown, it only gets more confusing.)

 

So I dunno, it may not be a good idea after all.

[Tom Keays]

Reviving a conversation from a couple of years ago...

I've been trying a couple of collaborative editing environments for the past several weeks. They both use MarkDown for document formatting, have built-in version control, some form of track changes, and allow collaborative editing. 

Draft. https://draftin.com/

Editorially. https://editorially.com/

I'm not sure this would really work with the current workflow, but wanted to put the idea out there. 

Tom

On Thu, Jul 21, 2011 at 8:19 PM, Jonathan Rochkind <roch...@jhu.edu> wrote:

I just had a crazy idea, put it out there for discussion, certainly not expecting any immediate action, even if people like it we'll want to stew on it for a while.

One of the most time consuming and annoying parts of editing the journal is getting things into HTML and editing the HTML without WordPress messing it up, etc.

Lately I've been using various "mostly plaintext but with conventions that can be formatted into html" formats, such as [markdown](http://daringfireball.net/projects/markdown/syntax), [textile](http://daringfireball.net/projects/markdown/syntax), and a few others. They are SO much easier to use. markdown is the most popular.

There are some markdown plugins for WP.

* What if we required authors to submit in markdown (basically plaintext with some pretty easy to remember conventions for indicating headers, lists, links, embedded images, etc)
* Then we just entered the markdown in WordPress
* Profit!

## Disadvantages

* We wouldn't be able to use fancy custom HTML anymore.  This has some pro's in enforcing consistency, but also some obvious cons.
* We'd probably have to give up on the COinS, which I think would actually be fine. Some years on, COinS has not really caught on, I'm not sure it provides a benefit commensurate to the effort it takes us, and we usually don't manage to do it right anyway. Few of our articles include links to non-open-access literature anyway.
* On the other hand, we can't give up code syntax highlighting. Not sure if WP markdown plugins would play nice with the syntax highlighter plugin, but they might.
* We'd have to figure out how to conveniently do notes/references too, especially for articles that want the (Smith 2000) style to be most readable.
* Not sure how we'd get things like our formatted captions on figures to work right, or center-aligned figures, etc.

So there'd be some challenges. But I suspect they could be overcome. And I think it would make our jobs so much easier, take out the most annoying and least rewarding thing editors spend time on. And, hey, forcing the limitation to the subset of HTML that markdown can represent would make an article-to-PDF converter a lot easier too.

## Note

This email is, as you may have guessed, in markdown.

[Peter Murray]

I like Markdown -- I think it is easy to learn although not necessarily easy to translate something like Word or Google Docs into. Mayble it would be a good option?


Peter

> To unsubscribe from this group and stop receiving emails from it, send an email to c4lj-discuss...@googlegroups.com.

> To post to this group, send email to c4lj-d...@googlegroups.com.

> Visit this group at http://groups.google.com/group/c4lj-discuss.
> For more options, visit https://groups.google.com/groups/opt_out.

--
Peter Murray
Assistant Director, Technology Services Development
LYRASIS
Peter....@lyrasis.org
+1 678-235-2955
800.999.8558 x2955

[Shawn Averkamp]

Markdown++

Editorially looks nice and would work well for sharing comments amongst the EC. I see there are some tools out there for converting Word to Markdown, but I can see potential bottlenecks when trying to collaborate with authors who may not be fluent.

[Tom Keays]

Editorially, at least as far as I can determine, does not have a way to preview the Markdown as HTML. It does have a way to export the document as Markdown and HTML, though, so that would probably suffice.

Draft has a preview mode and a more complete set of export options including Markdown, HTML, docx, and mobi (Kindle ebook) formats.

Since HTML export is an option for both, you could paste that into WordPress and then do the final formatting and document there.

One limitation with Markdown is no built-in syntax for laying out tabular data; you have to use native HTML. Since Editorial has no preview mode, you have do an export to see the HTML-view of the document. Less of a problem in Draft.

To my mind, Editorially has the stronger collaboration model: you explicitly invite collaborators by email and assign them roles of either Reviewer (can read and comment) or Editor (can read, comment, and edit). You have to be logged in to view the document and what you can do thereafter is determined by the assigned role. The owner of the document can revoke access. Documents are private by default. 

Draft has a looser collaboration system. If you have the Share URL, you can view the document. Anyone with the URL, once logged in, can edit the document. The owner won't know who has access to the document until they make changes to the document.

Both have similar versioning provisions. You have to explicitly save drafts to set rollback points. WordPress, on the other hand, more or less continuously saves versions during the editing process so you have lots of arbitrary rollback points.

Markdown was designed after the sort of character-based pseudomarkup that you used to frequently encounter in pure ASCII email. Gruber just formalized it. Coding URLs and images are the least intuitive elements in the Markdown syntax (but part of that for me is because Markdown is similar enough overall to DokuWiki syntax that I confuse which is which). But, yeah, the syntax could be a barrier to collaboration with some authors.

[Sara Amato]

Personally I have mixed feelings about this.   It would be wonderful if we could take some of the tedium/labor out of getting things into wordpress, no question about that.  And markdown looks simple enough.  However it sounds like we'd have to give up some things, or at least do have Tom put in some time to get them to continue to work, and I'm not convinced that authors would always be up to the task, as it might be one more thing for them, and us (e.g. seehttp://laurence.io/post/21454940154/a-better-website-editing-workflow-word-to-markdown).

The best experience I've had so far with editing has been with google docs, where both the editorial staff and the author could comment and change, and things were well tracked.  If the problem we are trying to solve is ease of entry into wordpress, I'd focus more on a tool for taking google doc html or rtf and cleaning it up for wordpress (I'm thinking along the lines of dreamweaver's 'clean up word html'.   I've played around a bit today with textutil, but so far no results that seem particularly useful to me. )

On the other hand if using one of these plugins allows for the generation of downloadable PDFs of the articles , I'd sign on in an instant….