Welcome to doconce Discussions!

[aless80]

Welcome!

We’re using Discussions as a place to connect with other members of our community. We hope that you:

• Ask questions you’re wondering about.
• Share practices and ideas.
• Engage with other community members.

To get started, you could tell us about

• How you use DocOnce and how does it help you;
• What functionalities you use most;
• What functionalities you are missing;
• Suggest any improvement (although you could consider to add an issue)

[lexnederbragt]

Hi! Great to have a place do discuss DocOnce and its development.

How you use DocOnce and how does it help you

I use DocOnce in my teaching. I prepare most of my material using DocOnce: slides, Jupyter Notebooks with live-coding and organised group work 'recipes', and Jupyter Notebooks with exercises with and without their solutions. I love the fact that I work modularly, i.e. being able to import other doconce files. For example, we have developed a large repository with individual exercises in DocOnce format, and I can create the exercise notebook for a certain course week by including the desired set of DocOnce file in a single do.txt file to create the notebooks without solutions, and with. I also like that I can keep everything under version control this way!

What functionalities you use most

# #include; deck.js slides; .html and .ipynb output formats; mixing text, (Python) code and mathematics seamlessly, exercises

What functionalities you are missing

I wish I could use DocOnce to generate a quiz with multiple choice questions in a format that allows collecting student's answers directly, without having to convert stuff manually to Mentimeter or such a tool. Or that DocOnce could output a file that could be used as input for such a quizzing service.

Some of the formatting in Jupyter Notebook output could be improved (admonitions, headers).

Maybe having a look at newer slide formats, especially RISE.

Suggest any improvement (although you could consider to add an issue)

See above. I'll post issues for more concrete, smaller stuff as they arise :-)

Keep up the good work, and let's try to grow the DocOnce community!

[MartinHeroux]

How you I use DocOnce

• keep experimental notes, then share as PDF or present (HTML)
• Writing blog posts (Markdown)
• Manuscript writing (LaTeX, PDF)

What functionalities do I use most

• pdflatex, html

What functionalities am I missing

• Would be nice to support additional journal formats (currently only a few are supported); alternatively this could be a tutorial on how to prepare LaTeX files from a given journal to be used as templates with DocOnce
• While HPL used Emacs (and thus provided some syntax highlighting), it would be nice to have support for a few more editors
  • Pycharm: I have a simple set-up that does some syntax highlighting, but it is limited in scope and not an actual plugin
  • gedit? geany?

Possible improvement

• As mentioned above, support for different LaTeX templates provided by publishers and journals

• It would be good to improve the packaging and versioning of DocOnce

  • what dependencies are essential, which ones are optional (and for what), which versions are needed
  • could some of the above be presented in a table or image for clarity
  • could DocOnce be published on PyPi (and include the dependencies that need to installed)
    • Update doconce is published in pypi, last updated in 2018; could this be reinstated and updated?!

• It would be good to have simple install instructions that could be used by beginners

• Streamline the options for installation

  • github (clone, python setup.py install)?
  • Pypi package?
  • conda package?
  • docker image?
  • virtualbox?

• Have summary tables/cheatsheets that summaries the key considerations/quirks that need to be kept in mind when publishing to different formats (e.g. math support, references, etc).

• Update what currently works (or does not not work) on Windows and Mac

[aless80]

At the time of writing (2020) I am the developer/principal maintainer of DocOnce. I work at CCSE at the University of Oslo and this is my page at CCSE with some info about myself. CCSE is commited to improve teaching practices by doing research in Science Education and releasing open source software. That is why I was asked to take over the development of DocOnce.

• How you use DocOnce and how does it help you;
• What functionalities you use most;
• What functionalities you are missing;

I do not really use DocOnce other than for development. That is why I sometimes feel I should learn more about the different formats. I do not use conda. I am reluctant to do it because I do not find it easier than pip, and I actually found myself struggling with conflicts. Instead I use virtual environments.

• Suggest any improvement

I'd like to restructure the code, in particular to improve modularization. I refrain from spending too much time on this because it would not improve how users experience DocOnce. IMO there are other priorities such as improving the installation procedure (work in progress) and the documentation. I'd like to improve the tests so that developers can check whether their changes work fine.

[lrhgit]

I found it a relief when conda was offered as a means to install doconce some years ago. However, the important thing is a very clear an simple explanation for installation, which also works for non-developers.

[MartinHeroux]

In response to Alessandro:
I totally agree about the tests. To not have full trust in the tests makes it hard to refactor code and add/change code.

This might be one of those things that it would be easier for you to do it all yourself given your expertise, but if you were interested in having some help, maybe coming up with an overview of what you have in mind for a DocOnce test suite (and maybe preparing a first series of tests -to serve as an example) would allow some of the other contributors to pitch in.

In response to irhgit:

I agree about having clear instructions for installation. At present I feel there is room for improvement.

I have commended on this above and in the dependencies discussion stream.

Another thing that would be nice is to determine to what extent DocOnce does (or does not) work on Mac and Windows. This is also part of the installation story.

[przemarbor]

Hi all,
I started to use DocOnce after quite a long time of search for some universal literate programming tool with the ability of generating documents for teaching (JupyterNotebook feature) or research. First, I stumbled upon Emacs and its org-mode which at first seemed too overwhelming, and then I discovered DocOnce. The idea behind DocOnce was something I was looking for. It was perfect for my needs. However with time passing I've begun to doubt whether it is the right choice.

My main question is the following: why did HPL decide to write his own markup language? After some time of struggling with Emacs I realized that probably all features that had attracted me to DocOnce were also implemented in Emacs (compiling with LaTeX, exporting to JupyterNotebook, markdown or any other format...). Basing on existance of doconce-mode.el I can guess that HPL edited his doconce documents also in Emacs. Why didn't he try to tailor Emacs org-mode to his needs and decided to develop his own markup language and his own software?

In other words, can any of you guys tell me what are the advantages of using doconce over org-mode? The only one that comes to my mind is Emacs' steep learning curve, however this is questionable. To get things rolling in DocOnce you need know LaTeX, Mako, Preprocess and few more tools. So, in my opinion, it's too demanding for a newbie to deal with DocOnce compilation errors by his/her own. That is why DocOnce cannot be recommended for collaborative writing unless all of you are good at programming. It's easier for me, it's true - I still don't know how to do achieve many things in org-mode while I can do them in DocOnce. However this does not convince me fully and I'm wondering wouldn't it be more reasonable to move to org-mode or just go back to plain LaTeX.

Please don't take my post personally. I think that amount of work put in this software is tremendous and it's not my intention to diminish HPL's or your work. I just wanted to share my doubts with you, with a hope that you will help me to convince myself to stay with DocOnce. ;)