Friday, December 26, 2014

sphinx-doc failing for manpage builder

Sphinx-doc (http://sphinx-doc.org/latest/index.html) is a utility to create intelligent and friendly documentation with existing support for Python and C/C++ projects.

It can produce documentation in varied formats like html, LaTeX, epub, Texinfo, manpages and plaintext. It has lots of other features and multiple community created extensions to hyper-activate its usability.

To give it a quick try "Sphinx - First Steps" tutorial can be used, or a bit more with "sampledoc tutorial".

Here we will be discussing issue faced whilst creating manpages from a sphinx-documented project raising issue for "man" builder not being supported.

The solution is very simple but being a beginner (or external user) makes one doubt it.

System package version of Sphinx-doc for some of the distros is still not above v1.0 and the manpage support is just found in those.
So, to counter this error just don't use system package for it but instead use "pip install sphinx".

If you don't have pip already, follow this article: https://pip.pypa.io/en/latest/installing.html .

Thursday, February 13, 2014

xopen : shell function to have verbose xdg-open : Mac's "open" alternative for Linux

I have been using xdg-open for sometime now, it's a utility similar to "open" utility popular among MacOSx users.

It enables you to open any file in the default "open with" program assigned to it's type. So, just passing any type of file to this utility would let you open it in the program it's supposed to open.

What is xdg-open?
source[1]: https://wiki.archlinux.org/index.php/xdg-open
source[2]: http://linux.die.net/man/1/xdg-open

There is just this little shell function, that makes your xdg-open usage a bit more verbose in case of errors (bad-syntax/ghost-file/ghost-program/open-failure) faced about the reason for it. And also shortens the access util name obviously.

xopen ()
{
    xdg-open "$@";
    _TMP_EXITCODE=$?;
    if [ "${_TMP_EXITCODE}" == "1" ]; then
        echo "[ERROR:] Error in command line syntax";
    else
        if [ "${_TMP_EXITCODE}" == "2" ]; then
            echo "[ERROR:] One of the files passed on the command line did not exist";
        else
            if [ "${_TMP_EXITCODE}" == "3" ]; then
                echo "[ERROR:] A required tool could not be found";
            else
                if [ "${_TMP_EXITCODE}" == "4" ]; then
                    echo "[ERROR:] The action failed";
                fi;
            fi;
        fi;
    fi;
    return $_TMP_EXITCODE
}