Discuss Offline docs app

[Sarvottam Kumar]

Hey,

I discussed the offline documentation earlier and I'm working on it.
Now after exploring the markdown application for viewing offline docs,
I found out that HTML is the best format to display documentation.

So, I think we should stick to 'mdbook' to convert markdown docs to
HTML and then display it in the application. Here, for displaying the
HTML content, I think Yelp is a good tool as Marek also suggested.

But I tried Yelp and discovered that it has a bug [1] to display HTML
file content. Even though it claims to support HTML, it always ends up
with the error "The URL can't be shown." I also asked at other forums
and the app maintainer as well, but no solution yet.

Then, I looked for another application and found GNOME Devhelp app
similar to Zealdocs. Devhelp is more simple and specially designed for
GNOME so I found it better than Zealdocs. If we choose Devhelp, my
only concern is that we always have to update the .devhelp2 index file
manually. Otherwise, it's a very good application.

So, can you guide me should I go for Devhelp or a new application from scratch?

Building a new app would have an advantage. First, we can make it as
minimal as we want and second it's a one-time investment. So for the
future, we only have to write md docs, convert to HTML using mdbook,
and just include in ISO. No one needs to know or maintain any index
file.

Also, GSoD will take more than two months to start, so before then I
can focus on the app and for GSoD only on the offline documentation.

What do you all suggest?


[1] https://bugzilla.redhat.com/show_bug.cgi?id=1443179

[David Hobach]

On 6/9/20 2:54 PM, Sarvottam Kumar wrote:
> Hey,
>
> I discussed the offline documentation earlier and I'm working on it.
> Now after exploring the markdown application for viewing offline docs,
> I found out that HTML is the best format to display documentation.
>
> So, I think we should stick to 'mdbook' to convert markdown docs to
> HTML and then display it in the application. Here, for displaying the
> HTML content, I think Yelp is a good tool as Marek also suggested.

Just a hint if it has not yet been evaluated:

There's also pandoc [2] out there.

It can convert from almost any doc format to almost any other.

E.g. md --> html|pdf|manpage|odt|docx|epub|...

Control is via command-line.

I used it at [3] and I'm pretty happy with it.

[2] https://pandoc.org/
[3] https://github.com/3hhh/blib-doc