mdview, a markdown viewer

[L18L]

Try it.

Tried.
All right.
Going to convert entire FAQ to mdview.....

Help can be launched by:

Code: Select all

export TEXTDOMAIN=fatdoghelp; mdview -x  /usr/share/doc/faqs ../home.md "" "Fatdog"

for now.

[L18L]

Going to convert entire FAQ to mdview.....

done
see Fatdog thread please.

[L18L]

Fatdog64's docs/faq are going to use this markdown format,
extension .md, to be viewed with mdview.

In order to enable SURE translations we are using GNU gettext.

gettext has 2 parameters:
1st is textdomain, (name of the .mo file)
2nd is the translatable message string (msgstr).
If it is one paramter only
then environment variable TEXTDOMAIN is being used.

Example:

Code: Select all

$(gettext fatdoghelp "The VLC media player in Fatdog64 can support BluRay playback.")

Space is cheap but there is no reason for wasting bytes.

Code: Select all

alias _=gettext

usually used with C sources would be nice
but does not work because _ is a markdown tag
and alias cannot be used in mdview AFAIK.

But this little wrapper /usr/bin/t_ does work:

Code: Select all

#!/bin/sh
gettext fatdoghelp "$1"; echo

... and above line is just:

Code: Select all

$(t_ "The VLC media player in Fatdog64 can support BluRay playback.")

___________________________________

How much saved?
About

Code: Select all

$((16 * `grep msgid fatdoghelp.pot | wc -l` / 1024))

= 23 kB.
Not that much but it is looking much nicer.
___________________________________

Speed?

Or an implementation of alias (alias t_=gettext) in mdview?

Code: Select all

$(t_ fatdoghelp"The VLC media player in Fatdog64 can support BluRay playback.")

___________________________________

poor man's solution?

Or maybe just renaming the textdomain?

Code: Select all

$(gettext fh "The VLC media player in Fatdog64 can support BluRay playback.")

___________________________________

Or both?

Code: Select all

$(t_ fh "The VLC media player in Fatdog64 can support BluRay playback.")

___________________________________

Your choice.
___________________________________

[disciple]

https://github.com/visionmedia/mad
Guys, have you considered compatibility with mad?

[musher0]

Hi, guys.

This viewer looks absolutely splendid, except for the obvious:
Maybe I'm missing a nut and a bolt (which is entirely likely!), but:

what editor do you use to create the marked text to be viewed?

Thanks in advance.

musher0

[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