Stencila Converter


#1

We have been doing quite a lot of work around Stencila Converter recently.
The Converter is one of the key components enabling users to collaborate without having to give up their preferred editing format.

The Converter leverages the awesome power of Pandoc to convert between formats, including Journal Publishing Tag Set (JATS) that Stencila supports. Hamish Mackenzie contributed a JATS reader to Pandoc (included in 2.0.6 release) and Nokome Bentley improved the existing Pandoc JATS writer.

One of the decisions we have to make when polishing up the Converter is which Pandoc enhanced Markdown extensions to enable or disable. There is probably no silver bullet but we want the Converter to output documents in Markdown standard that suits most users.

We’d be keen to hear your opinions!
You can either comment under this post directly or file in an issue in the Stencila Comvert repository.


#2

One vote for tex_math_dollars, so that we can use $ and $$, which is a widely supported syntax.


#3

Thank you! I filed in an issue https://github.com/stencila/convert/issues/27 - please feel free to comment there as well.


#4

I posted the following issue also on the repository: https://github.com/stencila/cli/issues/71

I’ve followed the installation instructions for MacOsX, moving the stencila executable to the /Applications folder. However when I open it by double click it automatically executes an exit command. Here’s the transcript:

dhcp-10-249-27-139:~ memyselfandi$ /Applications/stencila ; exit;

   stencila 0.30.1 

   USAGE

     stencila <command> [options]

   COMMANDS

     convert [input] [output]      Convert files or folders to other formats
     setup                         Setup required software dependencies     
     help <command>                Display help for a specific command      

   GLOBAL OPTIONS

     -h, --help         Display help                                      
     -V, --version      Display version                                   
     --no-color         Disable colors                                    
     --quiet            Quiet mode - only displays warn and error messages
     -v, --verbose      Verbose mode - will also output debug messages    

logout
Saving session...
...copying shared history...
...saving history...truncating history files...
...completed.

[Process completed]

Am I missing something here or is this a bug? thanks


#5

Hi @lollopus,

Thanks for your post and sorry for the problems. I had a look at the issue you filed in (thanks for that as well!) and I think there are two things that are getting tangled up here (which is the problem with our documentation which should make it clearer that at the moment different components which can work independently and not always are connected through the common interface).

The above problem you describe is, I assume, when you try to use the Stencila Converters? At the moment the easiest way to use them is through Stencila Command Line (CLI) which I suppose you installed following these instructions? Then to use it, you need to run the commands as described in your terminal -at the moment double clicking only runs a single stencila command
which displays help on how to use it in the terminal (which is the output you get).

I hope I understood correctly what your problem is - not, sorry! I

We have some examples which you can try converting. You could try downloading it, unzipping and then navigate to the hello-world directory and try some conversions (eg. stencila convert hello-world/hello-world.md hello-world/hello-world.docx)

Hope this helps!


#6

Hi @Aleksandra and thanks for your feedback!

I did follow the instructions but (on MacOsX High Sierra) had to issue
me$ PATH=$PATH:/Applications
before Terminal could see the “stencila” command without using its full path. This might need to be specified in the installation instructions (btw this will work only for the current Terminal session, I think)

Once I got over this initial obstacle I tested converting the hello-world.md example, but again encountered problems:

  1. MS World for mac (latest version) throws an error when attempting to open the file converted to ~/Desktop/output.docx
  2. converting to pdf I get errrors from Terminal:
    Error converting "/Users/lorenzocangiano/Downloads/examples-master/hello-world/README.md" to "/Users/lorenzocangiano/Desktop/output.pdf": Error calling Pandoc: message: pdflatex not found. Please select a different --pdf-engine or install pdflatex...
    Admittedly I didn’t attempt to install pdflatex.

No need to apologize on your part :slight_smile: as an eLife author and supporter I am enthusiastic about the concepts driving texture and stencila development. I look forward to helping out as a beta tester and, In fact, would love to dispense of Word, Endnote, etc for my next manuscripts.

A suggestion I have is to make it extra clear on your websites that these software are in full development, not quite ready for daily use in research but are publicly released to encourage feedback on desirable new features, etc. The current homepage of stencila, for instance, is very bold and attractive (something which definitely caught my attention) and may lead one to expect a smooth experience and an immediately viable alternative to “word processor and spreadsheet interfaces that you and your colleagues are already used to”. This I think would be counterproductive and should be avoided.

Lorenzo


#7

Hi Lorenzo, thank you for quick reply and all the feedback. This is really useful and we shall act upon it :slight_smile:

Re the installation on Mac - yes, what you did updated the PATH only for the current session. It actually may be a better practice to copy the stencila executable file to /usr/local/bin which should be in your PATH already. I will update the documentation accordingly.

Re the MS Word error - any chance you can copy-paste what it says (if it says anything?) or take a screenshot? If you have a moment, maybe file it as an issue Alternatively, I can do it and attribute to you.

Re the PDF- indeed that will require pdflatex (this is more Pandoc thing) but you’re right, it should be more specific in the documentation.

Very good point about the website - @nokome put a lot of work into it and looks like he did a great job! But sure, a short disclaimer may be useful.

Please stay tuned and keep sending us your comments!


#8

@Aleksandra As you recommended I opened an issue for the docx conversion error. Unfortunately Word says nothing about the exact problem with the file. Let me know if you want me to attempt other conversions on my system…

As an aside, this morning several of my posts were flagged as SPAM! Here’s a screenshot of what I’m presented with:

I would be suprised if they were perceived as offensive or off-topic by someone in the community (in that case I’d like to know why). I suspect this might be a server-initiated action on a new user posting too frequently since even my reply to the welcome bot was tagged as spam!


#9

As an aside, this morning several of my posts were flagged as SPAM!

@lollopus: yes, your posts where automatically flagged by the Discourse forum software we use, with the message “This new user tried to create multiple posts with links to the same domain (github.com). See the newuser_spam_host_threshold site setting.”. I have unflagged them now. Apologies for the inconvenience.

A suggestion I have is to make it extra clear on your websites that these software are in full development, not quite ready for daily use in research but are publicly released to encourage feedback on desirable new features, etc

I agree, that it needs to be much more clear on the front page that the software is in early beta. We also need to have a dedicated Roadmap page.