mdview, a markdown viewer

[disciple]

Markdown is very simple - use any text editor. In fact it's questionable whether it even needs a specialist "viewer", let alone an "editor".
Otherwise maybe you should try google if you want to find an editor with preview ability or special buttons so you don't have to type in your formatting or something...

[musher0]

Thanks, disciple.

In the meantime, I found John Gruber's "Daring Fireball" site, which explains
this mini formating language and how to use it:
http://daringfireball.net/projects/markdown/basics

BFN.

musher0

[L18L]

what editor do you use to create the marked text...

As quoted by disciple "use any text editor": I am using geany.

... to be viewed?

This text is to be viewed by (surprise): see title of this thread and initial post.

Using this we do need neither web server nor web browser for (run time translated) help files.

[musher0]

what editor do you use to create the marked text...

As quoted by disciple "use any text editor": I am using geany.

... to be viewed?

This text is to be viewed by (surprise): see title of this thread and initial post.

Using this we do need neither web server nor web browser for (run time translated) help files.

Wrong cut of sentence, Mister L18L Translator.
Ok I'll write it as in German: "MarkedTextToBeViewed" or
Marked-Text-To-Be-Viewed": as an entire and single concept.

And thanks for your usual trampling of my ideas.

Anyway, this entire thread is flawed because it contains no indication
as to how to produce the markdown text itself.

Where is the "legend" of this markdown language? Aside from Gruber's
site, which is not that clear. Hey, even maps have legends.

Where is a clear code for this markdown language? Hey, Morse Code is
clear, for example. LaTEX code is pretty clear too. This? Not so sure.

So IMO this entire thread is flawed because everyone is commenting on
the "view" side of it. Everyone is bowing to jamesbond with oooh's and
aaah's, but no one seems to have a clue about the "writing" side of it.

It stands to logic that if someone here doesn't provide the "code" or the
"legend" for this language, no text will be written in it, and there will be
nothing to use jamesbond's viewer with.

Until then: ha! this thread is completely pointless.

Sorry for being so frank.

BFN.

musher0

[musher0]

Almost forgot:
geany's markdown plugin is in limbo, but jEdit and gedit have working ones.

[musher0]

Untested converter

I'm still looking for a clear table of the markdown code, but at least I can
use Mark McCahill's pandoc-online above to convert text from whatever
format to markdown.

BFN.

[musher0]

Finally, substance:
Proper description of the markdown language
Proper cheatsheet for the markdown language
Phew. Now this thread is level again.

[musher0]

Hello all.

Attached is more "meat" on the markdown language, in html format.
(Just unzip and load in your browser.)

Of interest: the snip2code site has many markdown "snips" for those
who learn better by example.
https://www.snip2code.com/Explore/Public?q=markdown

I also chanced upon a reallly good markdown editor on-line.
https://stackedit.io/editor

(Sorry, the forum does not process https URLs.)

Enjoy.

musher0

[jamesbond]

@disciple: Guys, have you considered compatibility with mad?
Interesting link, thanks. "mad" seems to be a markdown-to-tty-text converter, useful if you want to view markdowns in console without GUI. It also supports a subset of markdown (mdview supports a slightly larger subset), so I guess in a way it is already compatible. mdview does not have the automatic search for mad-pages though; a simple script should be able to simulate that.

@musher0: "In the meantime, I found John Gruber's "Daring Fireball" site, which explains ..."
John Gruber is the creator of the Markdown format, and his website should be considered as authoritative (though I agree perhaps not the most clear). John supplies a markdown-to-HTML converter on that site, and anything that claims to be Markdown-compliant must produce the same output as John's converter.

That being said, mdview only supports a limited subset of the format, and what little it supports is given in its example/index.md file.

@musher0: "It stands to logic that if someone here doesn't provide the "code" or the "legend" for this language".
Yes, I am guilty of this. I should have linked John's page in the first post. I forgot that not everybody is familiar with markdown. I will edit the first post.

disciple and L18L have responded to you about the editor, but since you have found John's page, I may as well quote from it (emphasis mine):

The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

@musher0: "... pandoc-online above to convert text from whatever format to markdown ..."
Markdown is not a *target* format, it is a *source* format. The idea is you don't convert whatever *to* markdown; instead, you *write* in markdown and convert it to something else (mdview is in fact a "markdown-to-pango-formatted text" converter, and the engine behind it can be used to convert markdown to HTML too). Another point is that even if there is no viewer available, the source markdown documents are easy to read as plain text.

Markdown (especially the subset used in mdview) is easy to write because it simply reflects how people usually write emails.

Thanks for the other links about markdowns.

[disciple]

Yes, mad is a replacement for the classic 'man', which traditionally isn't included in Puppy. But if you're using a markdown based help you could include mad as well.

[musher0]

@jamesbond:
Thanks for shedding much needed add'l light on the subject.

BFN.

musher0

[L18L]

How about a run action?

Code: Select all

#!/bin/sh
DIR=${@%/*}
FILE=${@##*/}
HOME=$FILE
TITLE=${FILE%.*}
mdview $DIR $FILE "$HOME" "$TITLE"

text_x-markdown (replace the current symlink in fatdog)

In older pups with older shared-mime-info it is reported wrongly as application_x-genesis-rom .. see https://bugs.freedesktop.org/show_bug.cgi?id=27441

Excellent.
Extended for use in Fatdog's Help-Home&FAQ:

Code: Select all

#! /bin/sh

DIR=${@%/*}
FILE=${@##*/}
TITLE=${FILE%.*}

case $DIR in
 /usr/share/doc/faqs)  # fd64-701
  HOME=index.md
  TEXTDOMAIN=fatdoghelp mdview -x $DIR $FILE "$HOME" "$TITLE" 
  ;;
 *)
  HOME=$FILE
  mdview $DIR $FILE "$HOME" "$TITLE" 
  ;;
esac

This way it can easily be further extended.

[01micko]

Dunno what on earth I was thinking ( ), but maybe $HOME should be something else as to not cause conflict with the environmental variable, user's $HOME.

[L18L]

Dunno what on earth I was thinking ( ), but maybe $HOME should be something else as to not cause conflict with the environmental variable, user's $HOME.

Maybe it is not always necessary to think much
I had not noticed any conflict.

This HOME is mdview s Home (just the icon I am thinking now).
In Fatdog Help the Home icon refers to index.md
and Home has to be a link of its own....

Another non issue: TEXTDOMAIN does work without being exported.

[L18L]

Dunno what on earth I was thinking ( ), but maybe $HOME should be something else as to not cause conflict with the environmental variable, user's $HOME.

Maybe it is not always necessary to think much
I had not noticed any conflict.

Yes you are right!
There is a conflict of course.

I have renamed HOME to thisHOME
... and added README

#! /bin/sh

DIR=${@%/*}
FILE=${@##*/}
TITLE=${FILE%.*}
thisHOME=$FILE

case $FILE in
README*)
mdview -x $DIR $FILE "$thisHOME" "$TITLE"
;;
esac

case $DIR in
/usr/share/doc/faqs)
thisHOME=index.md
TITLE=Fatdog64
TEXTDOMAIN=fatdoghelp mdview -x $DIR $FILE "$thisHOME" "$TITLE"
;;
*)
mdview $DIR $FILE "$thisHOME" "$TITLE"
;;
esac

[L18L]

Suggest this /etc/xdg/rox.surceforge.net/MIME-types/text_x-markdown:

Code: Select all

#! /bin/sh

[ $(readlink $@) ] && FILE=$(readlink $@) || FILE=$@

DIR=${@%/*}
FILE=${FILE##*/}
TITLE=${FILE%.*}
thisHOME=$FILE
thisTEXTDOMAIN=$TEXTDOMAIN

case $FILE in
 README*)
  TITLE=${@%.*}
  thisTEXTDOMAIN=README
  ;;
esac

case $DIR in
 /usr/share/doc/faqs)
  thisHOME=index.md
  TITLE=Fatdog64
  thisTEXTDOMAIN=fatdoghelp
  ;;
esac

TEXTDOMAIN=$thisTEXTDOMAIN mdview -x $DIR $FILE "$thisHOME" "$TITLE" 

tested with translated README.md
LIESMICH.md symlinked

[jamesbond]

Following suggestion by disciple, the latest fossil version of mdview now supports output to console (stdout), as plain text (--text), text with vt100 codes (bold/color, works with urxvt/xterm/console) (--tty), and as html (--html); so in a way it is now compatible with "mad" (or in other words, subsumes "mad" functionality for converting markdown to decorated text).

Pipe --tty output to "less -R" for paging, if wished.

[step]

Following suggestion by disciple, the latest fossil version of mdview now supports output to console (stdout), as plain text (--text), text with vt100 codes (bold/color, works with urxvt/xterm/console) (--tty), and as html (--html); so in a way it is now compatible with "mad" (or in other words, subsumes "mad" functionality for converting markdown to decorated text).

Pipe --tty output to "less -R" for paging, if wished.

Great. Markdown was also born to be neat and readable on terminals. This feature makes a lot of sense. Thanks.

[charlie6]

Hi jamesbond,

i got mdview compiled on wheezy-3.5.2.11;
it opens the .md file coming with the tarball file (file.md, README.md, index.md)

i'd hope to open html files as the ones present in /usr/share/doc using the following command line:

Code: Select all

# mdview --html /usr/share/doc/ pburn.html

(process:29936): GLib-GObject-CRITICAL **: /build/buildd-glib2.0_2.33.12+really2.32.4-5-i386-eISom6/glib2.0-2.33.12+really2.32.4/./gobject/gtype.c:2722: You forgot to call g_type_init()

(process:29936): GLib-CRITICAL **: g_once_init_leave: assertion `result != 0' failed

(process:29936): GLib-GObject-CRITICAL **: g_object_new: assertion `G_TYPE_IS_OBJECT (object_type)' failed
^C

although this displays the raw pburn.html:

Code: Select all

# mdview -x /usr/share/doc pburn.html

I might have missed something...
Could you help me please ?

Thanks in advance
Charlie

[L18L]

Hi charlie6,

html is markup language
and md means mark down which is much simpler.

You might have expected to get an html viewer.
But it is a md viewer.

mdview --html generates fragments of html.

If you like to see pburn in markdown see attached file.
(It was just fun to copy it from browser into the .md file and do a few modifications)