RFC Offline Documentation
50 views
Skip to first unread message
Sarvottam Kumar
May 24, 2020, 3:54:25 PM5/24/20
to qubes-...@googlegroups.com, qubes...@googlegroups.com
Hello community,
The problem you're addressing (if any)
As stated earlier in my GSoD introduction, I have been getting
hands-on Qubes docs for weeks and have now finally decided to focus on
the specific idea "Offline Documentation". I chose it as I experienced
while using Qubes OS that there is a crucial need for guides for
beginners to get-go on Qubes after first boot (or in case unable to
access the internet).
Describe the solution you'd like
My solution involves a pre-constructed guidebook that can be included
in the ISO build and present it through a web browser app after the
first boot. For building docs, I'm using a "mdbook" tool that creates
an HTML book from markdown files. Basically, it compiles all markdown
files and renders to a single directory with index file `index.html`
and all other js and CSS files.
The guidebook is portable and can open on all platforms in offline
mode without any need for a 'http' server. Besides, here [1] I've
built sample docs and hosted online to show the basic structure of the
guidebook. Currently, I've not included any content, it's just a
minimal skeleton to show my approach that I'll follow to build the
final offline docs.
Where is the value to a user, and who might that user be?
This doc will serve all types of users who want to know and sometimes
troubleshoot the Qubes without the internet and online Qubes website.
Additional context
I've also tried 'Jekyll' and 'Sphinx' tool but I chose 'mdbook' over
them because I find it more simple, easy, and fully markdown focussed.
Jekyll is more for creating a static website and Sphinx uses
reStructuredText as its markup language.
Hence, being Qubes docs already in markdown, 'mdbook' suits the best
and easiest for any contributors as well who don't want to learn new
tools but knows markdown (that almost all contributors know). Also, it
would be a benefit to write content that can be used interchangeably
for both offline and online platforms.
I've tested the offline book by moving it to another OS where the
navigation links also work fine. The last thing, I want to mention
that instead of browser I want to build a minimal application just to
open the docs in AppVM so that users can open it whenever they want.
Here I'm looking for suggestions so feel free to share your opinion.
[1] https://qubes-os-offline.netlify.app/
Thanks
Sarvottam Kumar
The problem you're addressing (if any)
As stated earlier in my GSoD introduction, I have been getting
hands-on Qubes docs for weeks and have now finally decided to focus on
the specific idea "Offline Documentation". I chose it as I experienced
while using Qubes OS that there is a crucial need for guides for
beginners to get-go on Qubes after first boot (or in case unable to
access the internet).
Describe the solution you'd like
My solution involves a pre-constructed guidebook that can be included
in the ISO build and present it through a web browser app after the
first boot. For building docs, I'm using a "mdbook" tool that creates
an HTML book from markdown files. Basically, it compiles all markdown
files and renders to a single directory with index file `index.html`
and all other js and CSS files.
The guidebook is portable and can open on all platforms in offline
mode without any need for a 'http' server. Besides, here [1] I've
built sample docs and hosted online to show the basic structure of the
guidebook. Currently, I've not included any content, it's just a
minimal skeleton to show my approach that I'll follow to build the
final offline docs.
Where is the value to a user, and who might that user be?
This doc will serve all types of users who want to know and sometimes
troubleshoot the Qubes without the internet and online Qubes website.
Additional context
I've also tried 'Jekyll' and 'Sphinx' tool but I chose 'mdbook' over
them because I find it more simple, easy, and fully markdown focussed.
Jekyll is more for creating a static website and Sphinx uses
reStructuredText as its markup language.
Hence, being Qubes docs already in markdown, 'mdbook' suits the best
and easiest for any contributors as well who don't want to learn new
tools but knows markdown (that almost all contributors know). Also, it
would be a benefit to write content that can be used interchangeably
for both offline and online platforms.
I've tested the offline book by moving it to another OS where the
navigation links also work fine. The last thing, I want to mention
that instead of browser I want to build a minimal application just to
open the docs in AppVM so that users can open it whenever they want.
Here I'm looking for suggestions so feel free to share your opinion.
[1] https://qubes-os-offline.netlify.app/
Thanks
Sarvottam Kumar
Marek Marczykowski-Górecki
May 25, 2020, 10:54:39 PM5/25/20
to Sarvottam Kumar, qubes-...@googlegroups.com, qubes...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
On Mon, May 25, 2020 at 01:24:12AM +0530, Sarvottam Kumar wrote:
> Hello community,
Hi,
> The problem you're addressing (if any)
> As stated earlier in my GSoD introduction, I have been getting
> hands-on Qubes docs for weeks and have now finally decided to focus on
> the specific idea "Offline Documentation". I chose it as I experienced
> while using Qubes OS that there is a crucial need for guides for
> beginners to get-go on Qubes after first boot (or in case unable to
> access the internet).
The above sounds like two related projects:
1. Make existing documentation available offline, within the system
2. Write/restructure documentation specifically for introducing into the
system and/or troubleshooting most common issues.
I call them separate, because we'd like to avoid documentation
duplication as much as possible (avoid increased maintenance work). This
means, the offline version should be really about making available
in-system (possibly subset of) what is served on the website.
But with a decent plan, I believe it is possible to do both at once.
> Describe the solution you'd like
> My solution involves a pre-constructed guidebook that can be included
> in the ISO build and present it through a web browser app after the
> first boot.
A technical detail: I would be careful about requiring full web browser
in the system to access documentation. In normal case, like system
introduction, it should be fine. But for troubleshooting, you may find
yourself in a situation where you can't start any VM with a browser
installed and that's the reason why you are looking for the
documentation. So, better aim at a format that can be viewed with some
simple application. This may still be HTML, if you find a viewer simple
enough to be safe in dom0. This may need to restrict a HTML features in
use.
> For building docs, I'm using a "mdbook" tool that creates
> an HTML book from markdown files. Basically, it compiles all markdown
> files and renders to a single directory with index file `index.html`
> and all other js and CSS files.
Related to the above - I see it also has epub backend, and it's probably
possible to convert to various other formats too. So, I think using
mdbook should be generally fine, but the final format should be chosen
carefully.
Also, as mentioned above, offline documentation should not be
too-separate from online one. If mdbook enforces some specific layout or
format of markdown files, it may mean a need for some conversion tool
(again, I think that should be quite easy - for example stripping
frontmatter if I see correctly examples in mdbook docs).
> The guidebook is portable and can open on all platforms in offline
> mode without any need for a 'http' server. Besides, here [1] I've
> built sample docs and hosted online to show the basic structure of the
> guidebook. Currently, I've not included any content, it's just a
> minimal skeleton to show my approach that I'll follow to build the
> final offline docs.
Yes, this looks promising :)
I'd also include explicit troubleshooting section (but also see another
discussion on this ML about consolidating them).
> Where is the value to a user, and who might that user be?
> This doc will serve all types of users who want to know and sometimes
> troubleshoot the Qubes without the internet and online Qubes website.
>
> Additional context
> I've also tried 'Jekyll' and 'Sphinx' tool but I chose 'mdbook' over
> them because I find it more simple, easy, and fully markdown focussed.
> Jekyll is more for creating a static website and Sphinx uses
> reStructuredText as its markup language.
Yes, Sphinx uses different input format, and also is more focused on
developer documentation I think (features like extracting documentation
from the source code etc). We use Jekyll for our website and one of
approaches for offline documentation we've considered in the past was to
create another layout files for Jekyll to use when generating offline
docs. But indeed, using mdbook may be better approach.
> Hence, being Qubes docs already in markdown, 'mdbook' suits the best
> and easiest for any contributors as well who don't want to learn new
> tools but knows markdown (that almost all contributors know). Also, it
> would be a benefit to write content that can be used interchangeably
> for both offline and online platforms.
Yes, exactly.
> I've tested the offline book by moving it to another OS where the
> navigation links also work fine. The last thing, I want to mention
> that instead of browser I want to build a minimal application just to
> open the docs in AppVM so that users can open it whenever they want.
> Here I'm looking for suggestions so feel free to share your opinion.
Oh, you've covered this point already :) I would first try to search for
existing applications like that. There is for example Yelp[2], but maybe
there is something more lightweight.
> [1] https://qubes-os-offline.netlify.app/
[2] https://wiki.gnome.org/Apps/Yelp/
- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAl7MhOgACgkQ24/THMrX
1yzOogf/eHhHorYcWlPlv8RpxwQCjTQ7x5U+zhhuq/b1De8kHTRRTUDGoK6OmICB
YRaIxs3HjU61J0TX/otwTCGwmXM7c5DLqry+UK4Bhi3VYh/oCEIsiWOWg7wPRyhI
3BORYZDxjbTGGYz/E9G29qroSCCmOlhnA4VTEdsV9F7KXxcoWpcJBa5ZGbqBFtse
S33gK7ky4FWjbvmSMP3j8T3NqO7IPIo5016/X3B1vNeviT5hciY6WIcCuwOTdzzh
cyHZq8BpyG7mK9DmetSqIr1nGpNd7QuLKCSwb38+sawlEIS1GMbHm+9dRk6IFnAZ
2CGaI90XhR8GnrRfv1Ff35tVET3J0A==
=vP7I
-----END PGP SIGNATURE-----
Hash: SHA256
On Mon, May 25, 2020 at 01:24:12AM +0530, Sarvottam Kumar wrote:
> Hello community,
Hi,
> The problem you're addressing (if any)
> As stated earlier in my GSoD introduction, I have been getting
> hands-on Qubes docs for weeks and have now finally decided to focus on
> the specific idea "Offline Documentation". I chose it as I experienced
> while using Qubes OS that there is a crucial need for guides for
> beginners to get-go on Qubes after first boot (or in case unable to
> access the internet).
1. Make existing documentation available offline, within the system
2. Write/restructure documentation specifically for introducing into the
system and/or troubleshooting most common issues.
I call them separate, because we'd like to avoid documentation
duplication as much as possible (avoid increased maintenance work). This
means, the offline version should be really about making available
in-system (possibly subset of) what is served on the website.
But with a decent plan, I believe it is possible to do both at once.
> Describe the solution you'd like
> My solution involves a pre-constructed guidebook that can be included
> in the ISO build and present it through a web browser app after the
> first boot.
in the system to access documentation. In normal case, like system
introduction, it should be fine. But for troubleshooting, you may find
yourself in a situation where you can't start any VM with a browser
installed and that's the reason why you are looking for the
documentation. So, better aim at a format that can be viewed with some
simple application. This may still be HTML, if you find a viewer simple
enough to be safe in dom0. This may need to restrict a HTML features in
use.
> For building docs, I'm using a "mdbook" tool that creates
> an HTML book from markdown files. Basically, it compiles all markdown
> files and renders to a single directory with index file `index.html`
> and all other js and CSS files.
possible to convert to various other formats too. So, I think using
mdbook should be generally fine, but the final format should be chosen
carefully.
Also, as mentioned above, offline documentation should not be
too-separate from online one. If mdbook enforces some specific layout or
format of markdown files, it may mean a need for some conversion tool
(again, I think that should be quite easy - for example stripping
frontmatter if I see correctly examples in mdbook docs).
> The guidebook is portable and can open on all platforms in offline
> mode without any need for a 'http' server. Besides, here [1] I've
> built sample docs and hosted online to show the basic structure of the
> guidebook. Currently, I've not included any content, it's just a
> minimal skeleton to show my approach that I'll follow to build the
> final offline docs.
I'd also include explicit troubleshooting section (but also see another
discussion on this ML about consolidating them).
> Where is the value to a user, and who might that user be?
> This doc will serve all types of users who want to know and sometimes
> troubleshoot the Qubes without the internet and online Qubes website.
>
> Additional context
> I've also tried 'Jekyll' and 'Sphinx' tool but I chose 'mdbook' over
> them because I find it more simple, easy, and fully markdown focussed.
> Jekyll is more for creating a static website and Sphinx uses
> reStructuredText as its markup language.
developer documentation I think (features like extracting documentation
from the source code etc). We use Jekyll for our website and one of
approaches for offline documentation we've considered in the past was to
create another layout files for Jekyll to use when generating offline
docs. But indeed, using mdbook may be better approach.
> Hence, being Qubes docs already in markdown, 'mdbook' suits the best
> and easiest for any contributors as well who don't want to learn new
> tools but knows markdown (that almost all contributors know). Also, it
> would be a benefit to write content that can be used interchangeably
> for both offline and online platforms.
> I've tested the offline book by moving it to another OS where the
> navigation links also work fine. The last thing, I want to mention
> that instead of browser I want to build a minimal application just to
> open the docs in AppVM so that users can open it whenever they want.
> Here I'm looking for suggestions so feel free to share your opinion.
existing applications like that. There is for example Yelp[2], but maybe
there is something more lightweight.
> [1] https://qubes-os-offline.netlify.app/
[2] https://wiki.gnome.org/Apps/Yelp/
- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAl7MhOgACgkQ24/THMrX
1yzOogf/eHhHorYcWlPlv8RpxwQCjTQ7x5U+zhhuq/b1De8kHTRRTUDGoK6OmICB
YRaIxs3HjU61J0TX/otwTCGwmXM7c5DLqry+UK4Bhi3VYh/oCEIsiWOWg7wPRyhI
3BORYZDxjbTGGYz/E9G29qroSCCmOlhnA4VTEdsV9F7KXxcoWpcJBa5ZGbqBFtse
S33gK7ky4FWjbvmSMP3j8T3NqO7IPIo5016/X3B1vNeviT5hciY6WIcCuwOTdzzh
cyHZq8BpyG7mK9DmetSqIr1nGpNd7QuLKCSwb38+sawlEIS1GMbHm+9dRk6IFnAZ
2CGaI90XhR8GnrRfv1Ff35tVET3J0A==
=vP7I
-----END PGP SIGNATURE-----
Sarvottam Kumar
May 26, 2020, 3:50:40 PM5/26/20
to qubes-devel
On Tuesday, May 26, 2020 at 8:24:39 AM UTC+5:30, Marek Marczykowski-Górecki wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
On Mon, May 25, 2020 at 01:24:12AM +0530, Sarvottam Kumar wrote:
> Hello community,
Hi,
> The problem you're addressing (if any)
> As stated earlier in my GSoD introduction, I have been getting
> hands-on Qubes docs for weeks and have now finally decided to focus on
> the specific idea "Offline Documentation". I chose it as I experienced
> while using Qubes OS that there is a crucial need for guides for
> beginners to get-go on Qubes after first boot (or in case unable to
> access the internet).
The above sounds like two related projects:
1. Make existing documentation available offline, within the system
2. Write/restructure documentation specifically for introducing into the
system and/or troubleshooting most common issues.
I call them separate, because we'd like to avoid documentation
duplication as much as possible (avoid increased maintenance work). This
means, the offline version should be really about making available
in-system (possibly subset of) what is served on the website.
But with a decent plan, I believe it is possible to do both at once.
That's what actually I mean to say, a combination of both online existing
docs in offline mode and special documentation for troubleshooting (not written
before at the website).
docs in offline mode and special documentation for troubleshooting (not written
before at the website).
> Describe the solution you'd like
> My solution involves a pre-constructed guidebook that can be included
> in the ISO build and present it through a web browser app after the
> first boot.
A technical detail: I would be careful about requiring full web browser
in the system to access documentation. In normal case, like system
introduction, it should be fine. But for troubleshooting, you may find
yourself in a situation where you can't start any VM with a browser
installed and that's the reason why you are looking for the
documentation. So, better aim at a format that can be viewed with some
simple application. This may still be HTML, if you find a viewer simple
enough to be safe in dom0. This may need to restrict a HTML features in
use.
So, wouldn't it be better to view documentation in a simple markdown viewer app?
In this way, first, we can avoid any format conversion app (mdbook) for Qubes default docs i.e. md to html.
second, we won't need any browser or any HTML feature to worry about security.
And, markdown viewer app would be more minimal and lightweight.
In this way, first, we can avoid any format conversion app (mdbook) for Qubes default docs i.e. md to html.
second, we won't need any browser or any HTML feature to worry about security.
And, markdown viewer app would be more minimal and lightweight.
> For building docs, I'm using a "mdbook" tool that creates
> an HTML book from markdown files. Basically, it compiles all markdown
> files and renders to a single directory with index file `index.html`
> and all other js and CSS files.
Related to the above - I see it also has epub backend, and it's probably
possible to convert to various other formats too. So, I think using
mdbook should be generally fine, but the final format should be chosen
carefully.
Also, as mentioned above, offline documentation should not be
too-separate from online one. If mdbook enforces some specific layout or
format of markdown files, it may mean a need for some conversion tool
(again, I think that should be quite easy - for example stripping
frontmatter if I see correctly examples in mdbook docs).
> The guidebook is portable and can open on all platforms in offline
> mode without any need for a 'http' server. Besides, here [1] I've
> built sample docs and hosted online to show the basic structure of the
> guidebook. Currently, I've not included any content, it's just a
> minimal skeleton to show my approach that I'll follow to build the
> final offline docs.
Yes, this looks promising :)
I'd also include explicit troubleshooting section (but also see another
discussion on this ML about consolidating them).
I will share a proper doc structure with all sections and contents that should be a part of offline docs.
Marek Marczykowski-Górecki
May 26, 2020, 5:09:52 PM5/26/20
to Sarvottam Kumar, qubes-devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Hash: SHA256
On Tue, May 26, 2020 at 12:50:39PM -0700, Sarvottam Kumar wrote:
>
>
> On Tuesday, May 26, 2020 at 8:24:39 AM UTC+5:30, Marek Marczykowski-Górecki
> wrote:
> > A technical detail: I would be careful about requiring full web browser
> > in the system to access documentation. In normal case, like system
> > introduction, it should be fine. But for troubleshooting, you may find
> > yourself in a situation where you can't start any VM with a browser
> > installed and that's the reason why you are looking for the
> > documentation. So, better aim at a format that can be viewed with some
> > simple application. This may still be HTML, if you find a viewer simple
> > enough to be safe in dom0. This may need to restrict a HTML features in
> > use.
>
>
> So, wouldn't it be better to view documentation in a simple markdown viewer
> app?
> In this way, first, we can avoid any format conversion app (mdbook) for
> Qubes default docs i.e. md to html.
> second, we won't need any browser or any HTML feature to worry about
> security.
> And, markdown viewer app would be more minimal and lightweight.
Yes! That would be much better, I totally forgot that is be an option :)
>
>
> On Tuesday, May 26, 2020 at 8:24:39 AM UTC+5:30, Marek Marczykowski-Górecki
> wrote:
> > A technical detail: I would be careful about requiring full web browser
> > in the system to access documentation. In normal case, like system
> > introduction, it should be fine. But for troubleshooting, you may find
> > yourself in a situation where you can't start any VM with a browser
> > installed and that's the reason why you are looking for the
> > documentation. So, better aim at a format that can be viewed with some
> > simple application. This may still be HTML, if you find a viewer simple
> > enough to be safe in dom0. This may need to restrict a HTML features in
> > use.
>
>
> So, wouldn't it be better to view documentation in a simple markdown viewer
> app?
> In this way, first, we can avoid any format conversion app (mdbook) for
> Qubes default docs i.e. md to html.
> second, we won't need any browser or any HTML feature to worry about
> security.
> And, markdown viewer app would be more minimal and lightweight.
- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
1ywTxgf/RFVeL1RCUtQL344R96HbhIX2XUAqDBQq1nHthHtl2g75AmRjWitWH1W3
iGgEBfoYj9yJdqZixXEn6D1fF8VpIbeOQEyIvcxLpzbdBeRYlz0H4oTvKMB6r3WO
lH1EO2sBI4u3XCwEKQu8D03sWpwdrWpZbHzNgOLl3H5B8HIbBzuBu0FEjTDpktBz
aJO6wCyPx+PQgVeWozb7ZRJuJsgvRvpb1NflaHRmEWi+gahoWggOK6SrsQsPoM4x
ikvgQg8tKcIGeepbN57VZT3f8xGmqdn3bUF4K8cdrNbGqZ6SSOmpMJyTO3AAkl+G
sMKjRnwtKus62nJ+jI+0H40BAyFglg==
=vR31
-----END PGP SIGNATURE-----
Sarvottam Kumar
May 27, 2020, 1:52:03 PM5/27/20
to qubes-devel
On Wednesday, May 27, 2020 at 2:39:52 AM UTC+5:30, Marek Marczykowski-Górecki wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
On Tue, May 26, 2020 at 12:50:39PM -0700, Sarvottam Kumar wrote:
>
>
> On Tuesday, May 26, 2020 at 8:24:39 AM UTC+5:30, Marek Marczykowski-Górecki
> wrote:
> > A technical detail: I would be careful about requiring full web browser
> > in the system to access documentation. In normal case, like system
> > introduction, it should be fine. But for troubleshooting, you may find
> > yourself in a situation where you can't start any VM with a browser
> > installed and that's the reason why you are looking for the
> > documentation. So, better aim at a format that can be viewed with some
> > simple application. This may still be HTML, if you find a viewer simple
> > enough to be safe in dom0. This may need to restrict a HTML features in
> > use.
>
>
> So, wouldn't it be better to view documentation in a simple markdown viewer
> app?
> In this way, first, we can avoid any format conversion app (mdbook) for
> Qubes default docs i.e. md to html.
> second, we won't need any browser or any HTML feature to worry about
> security.
> And, markdown viewer app would be more minimal and lightweight.
Yes! That would be much better, I totally forgot that is be an option :)
Cool then. I'm looking for some already built markdown viewer or else I'll go from scratch.
tetra...@danwin1210.me
May 29, 2020, 5:33:37 AM5/29/20
to Marek Marczykowski-Górecki, Sarvottam Kumar, qubes-...@googlegroups.com, qubes...@googlegroups.com
On Tue, May 26, 2020 at 04:54:31AM +0200, Marek Marczykowski-Górecki wrote:
>The above sounds like two related projects:
>1. Make existing documentation available offline, within the system
For the record, I have also run into the listed problems, and my
>The above sounds like two related projects:
>1. Make existing documentation available offline, within the system
solution has been "have a VM where I git-clone all the documentation
repos".
Then I can just browse the repos when I need docs.
I find the markdown files are human-readable enough for troubleshooting
purposes that I can just read them with vim.
Holger Levsen
May 29, 2020, 6:49:01 AM5/29/20
to qubes-...@googlegroups.com, qubes...@googlegroups.com
On Fri, May 29, 2020 at 09:33:24AM +0000, tetrahedra via qubes-devel wrote:
> I find the markdown files are human-readable enough for troubleshooting
> purposes that I can just read them with vim.
same here.
> I find the markdown files are human-readable enough for troubleshooting
> purposes that I can just read them with vim.
--
cheers,
Holger
-------------------------------------------------------------------------------
holger@(debian|reproducible-builds|layer-acht).org
PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C
Reply all
Reply to author
Forward
0 new messages