mdview, a markdown viewer

[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)

[L18L]

Made in Fatdog64_701 where
xgettext msguniq msgunfmt msgmerge msgfmt
are included.

Code: Select all

#!/bin/sh

TITLE='translate .md files'

usage () { 
  die  "
  Create / edit translation file (GNU message catalog) from md files
  usage: $0 [file.md|directory]
 
    case file.md then each file under /etc /root /usr /var  will be processed 
    in case of directory then each file *.md in this directory will be processed   
        
   example 1: $0 README.md
   example 2: $0 /usr/share/doc/faqs/
   
   At least one file must contain %%textdomain <TEXTDOMAIN> 
   Translation is stored in $TEXTDOMAIN/${LANG%_*}/LC_MESSAGES/<TEXTDOMAIN>.mo
   Existing translations are always being re-used (msgmerge)
 "	
}

die () { [ $DISPLAY ] && Xdialog --title="$TITLE" --msgbox "$1" 0 0 || echo $1; exit 1; }

[ `whoami` = root ] || die "This tool is for root only."

create_pot () {
  # create ${WD}/${aTEXTDOMAIN}.pot file from .md file(s) using xgettext and mdview --po
  aTEXTDOMAIN=$1
  FILES=$2
  local MD=MD$$
  
  echo " " | xgettext -o ${WD}/${aTEXTDOMAIN}_.pot -L shell --package-name=$aTEXTDOMAIN --from-code=UTF-8 --force-po -
  sed -i 's/charset=CHARSET/charset=UTF-8/' ${WD}/${aTEXTDOMAIN}_.pot
  echo "" >> ${WD}/${aTEXTDOMAIN}_.pot

  for aFILE in $FILES; do
    grep -v '$(g' ${aFILE} > $MD
    mdview --po        ""   $MD >> ${WD}/${aTEXTDOMAIN}_.pot
    xgettext -L shell $aFILE -j -o ${WD}/${aTEXTDOMAIN}_.pot
  done

  msguniq -u --to-code=UTF-8 -o ${WD}/${aTEXTDOMAIN}.pot ${WD}/${aTEXTDOMAIN}_.pot 
  rm ${WD}/${aTEXTDOMAIN}_.pot
  rm $MD
}

create_po () {
  aTEXTDOMAIN=$1
  if [ -f "${TRANSLATED}" ]; then
    msgunfmt ${TRANSLATED} -o - > ${WD}/${aTEXTDOMAIN}_OLD.po
  else
    urxvt -e msginit --no-translator --no-wrap --locale=${transLANG} --input=${WD}/${aTEXTDOMAIN}.pot --output-file=${WD}/${aTEXTDOMAIN}_OLD.po
  fi 
}


translate_until_error_free  () {
  ATEXTDOMAIN=$1
  #code from momanager by Barry Kauler	
  #130502 L18L/BK: stay in a loop if there is an error converting .po to .mo...
  ABORTFLG=0
  cp -f $WD/${ATEXTDOMAIN}.po $WD/${ATEXTDOMAIN}.poBACKUP1
  while true ; do
    killall geany 2> /dev/null #otherwise geany will return immediately and continue executing this script.
    sleep 0.5

    geany $WD/${ATEXTDOMAIN}.po

    if [ ! diff -q $WD/${ATEXTDOMAIN}.poBACKUP1 $WD/${ATEXTDOMAIN}.po  >/dev/null 2>&1 ] ; then
      ABORTFLG=8
      break
    fi
    msgfmt --output-file=- $WD/${ATEXTDOMAIN}.po >/dev/null 2> $WD/po-2-mo.err
    [ ! -s $WD/po-2-mo.err ] && break

    pupdialog --background '#FF8080' --backtitle "${0##/*}: po to mo fail" --extra-button --yes-label "Fix" --no-label "Abort" --extra-label "Revert" --yesno "There are errors in the .po file:

`cat $WD/po-2-mo.err`

NOTE: The above error message is logged to $WD/po-2-mo.err

Click the 'Fix' button to edit the .po file again...
Click 'Revert' to go back to original .po file, and try again...
Click 'Abort' to give up..." 0 0
    case $? in
      0)  continue  ;; #Fix
      3)  cp -f $WD/${ATEXTDOMAIN}.poBACKUP1 $WD/${ATEXTDOMAIN}.po ; continue ;; #Revert
      *)  ABORTFLG=9 ; break ;; #1=Abort
    esac
  done
  
  if [ $ABORTFLG -eq 0 ];then
    rxvt -e msgfmt --check --output-file=$WD/${ATEXTDOMAIN}.mo $WD/${ATEXTDOMAIN}.po
    pupdialog --background yellow --colors --backtitle "${0##/*}: post-edit mo" --yes-label "OK" --no-label "Cancel" --yesno "The file $WD/${ATEXTDOMAIN}.po has been edited and converted to $WD/${ATEXTDOMAIN}.mo. If all went well, click the \ZbOK\ZB button to copy it to \Zb${TRANSLATED}\ZB. Note, as a precaution, the old mo file is at $WD/${ATEXTDOMAIN}.moOLD." 0 0
    ABORTFLG=$?
  fi

  if [ $ABORTFLG -eq 0 ];then
    cp -f $WD/${ATEXTDOMAIN}.mo "${TRANSLATED}"
  else
    pupdialog --background pink --backtitle "${0##/*}: mo edit aborted" --msgbox "You have declined to update the mo file. Ok, the previous one has been retained." 0 0
  fi
} 

##############################

case $1 in -*) usage ;; esac

read transLANG < $FATDOG_STATE_DIR/language #ex:de_BE.UTF-8
[ "$transLANG" ] || transLANG=$LANG
[ "$transLANG" ] || die "Sorry, need language LANG."
transLANG=${transLANG%_*} #ex:de

WD=/tmp/md; mkdir -p $WD

[ "$1" ] && FROM=`realpath "$1" 2>/dev/null`

[ $FROM ] || FROM=$(Xdialog --title "$TITLE to $transLANG" --backtitle="Choose .md file \n(or cancel to select a directory)" --no-buttons --fselect $HOME 0 0 2>&1)
[ "${FROM##*.}" = "md" ] || [ -d $FROM ] || die "no .md file selected"

[ $FROM ] || FROM=$(eval Xdialog --title \"$TITLE to $transLANG\" --backtitle=\"All .md files in directory:\" --no-buttons --dselect /usr/share/doc/faqs/ 0 0 2>&1)
[ ${FROM##*.} = md ] || [ -d $FROM ] || die "no .md file found in $FROM"

if [ -d $FROM ]; then
  FILES="`ls ${FROM}/*.md`"
else
  FILES="`find /etc /root /usr /var -maxdepth 3 -wholename ${FROM}`"
fi
aTEXTDOMAIN="`grep -m1 %%textdomain $FILES | cut -d' ' -f2  | uniq `"
[ "$aTEXTDOMAIN" ] || die "no %%textdomain found"

TRANSLATED=${TEXTDOMAINDIR}/${transLANG}/LC_MESSAGES/${aTEXTDOMAIN}.mo

create_pot $aTEXTDOMAIN "$FILES"
create_po $aTEXTDOMAIN
msgmerge ${WD}/${aTEXTDOMAIN}_OLD.po ${WD}/${aTEXTDOMAIN}.pot -o - > $WD/${aTEXTDOMAIN}.po

# remove comment sign, ex: change #~ msgid "bla" to msgid "bla"
sed -i 's/^#~ //' $WD/${aTEXTDOMAIN}.po #that is: keep unused translations !
sync
translate_until_error_free $aTEXTDOMAIN

exit 0

Used to translate mdview's examples/.
(small changes in index.md [attached])
25 messages....

[step]

@jamesbond, is there a way to start mdview with X11 geometry arguments like WxH+X+Y, or any way to start it in a given screen position with given window dimensions?

[L18L]

Recent momanager can.

mdview --po is automatically used with .md files that have a %%textdomain.

Note, you must have installed latest mdview, see 1st post of this thread, download,

Code: Select all

make

and copy executable mdview to /usr/bin.

Example file :

Code: Select all

%%textdomain mdview

This document contains list of all supported features.

------------------------------------------------------

%%nopot yes
**%%textdomain** domain

%%nopot no

The above line should be invisible, it sets the translation domain 
for use with this document (no-standard).

# Heading 1

This is also heading 1
===

## Heading 2

This is also heading 2
---

### Heading 3

This is a ruler

---

This one too

***

Bullets (only unordered supported for now)

%%nopot yes

 * a
 * b
 * c
 
%%nopot no

Codeblocks (4 spaces or tabs preceded everyline):
	function a()
	  b="*c*"
	}

### Inline styles

*italic1*, _italic2_, **bold1**, __bold2__, `inline code`, and `inline code again`, then 
**_bold-italic1_**, __*bold-italic2*__, and
"Smart double-quoting", 'smart single-quoting', em-dash: -- .

We also have non-standard ---strikethrough---.

Links:
* [Link to another file](file.md)
* [HTTP link to google](http://www.google.com) "Google Search"
* [HTTPS link to google](https://www.google.com)
* This is not a link: http://www.google.com 
* This is not a link: https://www.google.com

Inline image support: ![Tux](linux3.png)

(image path is always relative to document directory)

If you use the -x option, executable code is supported: $(echo '$LANG') is $(echo $LANG).
[Quoting-test for exec mode](quote-test.md).

**The End**

---

## Appendix: About translations

Default is create translation for **entire line** which can be a very long line (a paragraph <p> in terms of markup).

### No ---Translation---

A line starting with **tab** or **4 spaces** is NOT translated.

If you have a line which must **not** be translated (always code, maybe a name, parameter, etc) mark the line by %%nopot tags (nopot yes and nopot no) :

%%nopot yes

**%%nopot** yes

Let these English lines stay English only.

Nothing inside these tags will go into translation file.

**%%nopot** no

%%nopot no

Save it to e.g. /root/examples/mdview.md
and new momanager will present it for translation.

Feedback welcome.

EDIT: Here i s how it looks (untranslated)

[L18L]

bump
not just because I am always unseccessfully searching this in "Documents"...

mdview uses internal gettext i.e. entire line is a translatable message.

This is not really new,
But really new is:

You can use one textdomain for scripts and .md file.
This should be conveniant for help and/or README files.

ex: the app has textdomain apple.
define

Code: Select all

export TEXTDOMAIN=apple 

in the scripts
and define

Code: Select all

%%textdomain apple

in their .md files.
Next version of momanager can handle this so that translators see and translate just one file apple.po.

( Next version of momanager can handle also technosaurus' method additionally so that translators see and translate just one translation file.)

[step]

I tried to make me like this type of convenience several times, but I couldn't convince myself for the following reasons:
1. mdview is not a puppy standard, it's a Fatdog add-on.
2. mdview markdown support has some limits
3. What are the advantages of creating HTML documentation and giving that out to translate vs giving the md file out to translate? I still need to figure that out.
If the perceived benefits aren't readily apparent, gettexting md files is a hard sell, IMO.

[L18L]

I tried to make me like this type of convenience several times, but I couldn't convince myself for the following reasons:
1. mdview is not a puppy standard, it's a Fatdog add-on.

You forgot to say: It is new!
[EDIT]And you forgot to say: it is not an Ubuntu standard...[/EDIT]

2. mdview markdown support has some limits

Everything has some limits.

3. What are the advantages of creating HTML documentation and giving that out to translate vs giving the md file out to translate? I still need to figure that out.

Give out is publish?
Both of these are not good in my opinion as translators have to know some rules of html or mdview's markdown.
Translators are used to translate msgid to msgstr.

If the perceived benefits aren't readily apparent, gettexting md files is a hard sell, IMO.

There isn't anything to sell.

It is all free.

[step]

@jamesbond, I think I found a bug. Attached an md file to reproduce the issue. Essentially, when a line starts with [2] and includes matching brackets the text between [2] and the brackets included disappears. Version 2016.02.04 built on Thu Feb 4 07:09:52 2016.

[step]

@jamesbond, there's another issue concerning fenced code blocks and translations. I just realized that mdview --po doesn't output the text inside fenced blocks. On one hand that makes sense - it's source code after all - on the other hand it is a problem, because that text becomes invisible to the translation process, so it's hard to realize that it even exists before deciding if it should be translated or not.

There are valid cases for using fenced blocks for text other than source code, which should therefore be translated. So I'm proposing a work-around which I think doesn't break the fenced block syntax.

Code: Select all

```
this text is pre-formatted and hidden to gettext
```

vs.

Code: Select all

```gettext
this text is pre-formatted and it's also gettexted
```

This should work, since GFM fenced blocks can take an optional language tag to select appropriate syntax highlightling rules. GFM seems to ignore unknown tags, so here 'gettext' is passed as a language tag but mdview interprets it as an operational directive. What do you think?

----
Reproduce issue by

Code: Select all

# cat >> /tmp/zz.md
HAL's typewriter ticked a message:
```
I can't let you do that, David, I can't let you turn me off.
```
David was afraid.

# mdview --po /tmp/zz.md
#: //tmp/zz.md:1
msgid "HAL's typewriter ticked a message:"
msgstr ""

#: /tmp/zz.md:5
msgid "David was afraid. "
msgstr ""

[step]

@jamesbond, here's another test case for the bug reported two posts above

Code: Select all

 * Run mdview[3] to test your translation of markdown files (see below)

This is rendered as "* Run mdview3" and nothing else.

[step]

@jamesbond

...I'm proposing a work-around which I think doesn't break the fenced block syntax.

Code: Select all

```gettext
this text is pre-formatted and it's also ouput with mdview --po
```

I'm attaching a patch file, which implements the above work-around, for you and anyone else interested to review. Patch file against fossil 4fb552f2b09ca5ec 2016-02-04 07:11:16.

I still haven't started debugging the other issue I reported.

edit 20160223 I'm attaching a second patch file, which contains the first one. This file adds tests for the proposed patch and turns off translation of GitHub codeblocks unless they are marked "```gettext```". I'm not sure if you left translations enabled for GH codeblocks intentionally, but I think that disabling translations is consistent with all other types of codeblocks. Once again, "```gettext```" has a dual purpose, 1) enable outputting codeblock text with option --po, and 2) translating such text in normal operation.