ePub output

[chrisvire]

Could a GitHub action be added that would convert the html files into an ePub document output?

[jamespostsil]

This would be of interest for Paratext users as well. ePub or PDF format? PDF might be more helpful for desktop users (most would probably already have a PDF reader installed).

[chrisvire]

There is an epub target in the Makefile and make.bat. I tried to make epub on Windows, macOS, and Linux with no luck. There is no documentation on what to install. I installed what I could figure out, but I still ended up with this error:

On Mac:

  File "/usr/local/Cellar/sphinx-doc/7.0.0/libexec/lib/python3.11/site-packages/sphinx/config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/hubbard/codereview/usfm/docs/conf.py", line 125, in <module>
    import sphinx_rtd_theme
ModuleNotFoundError: No module named 'sphinx_rtd_theme'

On Windows:

Traceback (most recent call last):
  File "C:\Python311\Lib\site-packages\sphinx\config.py", line 354, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\CHubbard\src\usfm\docs\conf.py", line 125, in <module>
    import sphinx_rtd_theme
ModuleNotFoundError: No module named 'sphinx_rtd_theme'

[klassenjm]

Hi @chrisvire, @jamespostsil

I suspect what you need to do is pip install sphinx_rtd_theme. However -- I've not had much success with other (non-html) builds from Sphinx for this documentation. That's been a big disappointment, and I know it's been frustrating for people. It's possible that newer versions of Sphinx from what I've last tried will be able to make a PDF or ePub.

With this said, there is a small group working on a few things related to USFM-USX specification. The USFM and USX docs are being re-created as a combined set, using Asciidoc and Antora. You can see work in progress here - https://docs.usfm.bible. This is not finished. The search tool is much improved. Antora will generate PDF output as well. You can find an example PDF for the current docs here: https://github.com/usfm-bible/docs.usfm.bible/tree/gh-pages/

I'm sure work is needed to improve the layout (it's not ready to make a book out of) -- but it does following the web docs structure closely, with a complete set of bookmarks for navigation.

[jamespostsil]

Great to know you're working on improving the docs! I noticed you can search for "\f" and it comes up with a number of results, which IS a great improvement. Plus the dynamically updating feature (can't remember what it's called) that searches as you type.

Do you have an estimate for when the new version will be available? It doesn't seem worth trying to finagle a PDF out of a system that will be replaced soon.

Thanks for letting us know,

James

--

James Post

Language Technology Consultant SIL International @.***

On Mon, May 8, 2023 at 10:35 AM Jeff Klassen @.***> wrote:

Hi @chrisvire https://github.com/chrisvire, @jamespostsil https://github.com/jamespostsil

I suspect what you need to do is pip install sphinx_rtd_theme. However -- I've not had much success with other (non-html) builds from Sphinx for this documentation. That's been a big disappointment, and I know it's been frustrating for people. It's possible that newer versions of Sphinx from what I've last tried will be able to make a PDF or ePub.

With this said, There is a small group working on a few things related to USFM-USX specification. The USFM and USX docs are being re-created as a combined set, using Asciidoc and Antora. You can see work in progress here

• https://docs.usfm.bible. This is not finished. The search tool is much improved. Antora will generate PDF output as well. You can find an example PDF for the current docs here: https://github.com/usfm-bible/docs.usfm.bible/tree/gh-pages/

I'm sure work is needed to improve the layout (it's not ready to make a book out of) -- but it does following the web docs structure closely, with a complete set of bookmarks for navigation.

— Reply to this email directly, view it on GitHub https://github.com/ubsicap/usfm/issues/144#issuecomment-1538769633, or unsubscribe https://github.com/notifications/unsubscribe-auth/AZP5EWKWOMECASPMN7XE2M3XFEVEXANCNFSM6AAAAAAXTK2L7M . You are receiving this because you were mentioned.Message ID: @.***>

[klassenjm]

Personally, I would not try very hard to get a PDF output. I've tried, including going via a LaTeX build first. If someone requires an offline copy right now, I would just grab a copy of the HTML docs in this zip file, unpack, and browse locally.

https://markups.paratext.org/wp-content/uploads/2020/04/usfm-docs_3.0.1.zip

Estimate: A couple of months? Part of the process happening now is not only documentation but developing a grammar which clearly defines valid USFM and USX, independent of a particular editor. It's part time work for a few people, but it is moving along steadily.