Merge qubes-attachment into qubes-doc

[andrewdavidwong]

@marmarek (comment on #1200):

While at it - IMO it's good idea to merge attachments repository into
doc. Or at least place there files used in /doc/. This would make much
easier to make offline copy of the whole documentation: #1019

[andrewdavidwong]

OK, so the way to do this manually would involve moving the files which currently reside in qubes-attachment into a directory in qubes-doc, then finding every place in the documentation pages which refers to one of these files and updating the path to that file.

Most of them are images which get included like this:

![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)

Which would have to be changed to something like this:

![r2-split-gpg-5.png](/doc/img/SplitGpg/r2-split-gpg-5.png)

Can this be done programmatically? (I'm guessing it can.) Anyone want to tackle it (programmatically or manually)?

[andrewdavidwong]

OK, so the way to do this manually would involve moving the files which currently reside in qubes-attachment into a directory in qubes-doc, then finding every place in the documentation pages which refers to one of these files and updating the path to that file.

Most of them are images which get included like this:

![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)

Which would have to be changed to something like this:

![r2-split-gpg-5.png](/doc/img/SplitGpg/r2-split-gpg-5.png)

Can this be done programmatically? (I'm guessing it can.) Anyone want to tackle it (programmatically or manually)?

[andrewdavidwong]

A more general question: Are we sure we want to do this? Doing so would significantly increase the size of qubes-doc. Since qubes-doc is currently just text files, it's only 671.5 kB, while qubes-attachment is 32.8 MB.

The benefit would be, as @marmarek pointed out, that it would be easier to make an offline copy of the documentation (including images), since there would only be one repo to clone. But what if someone wants a minimal, lightweight copy of just plain text documentation? Not every conceivable device and program which a user might use to view offline documentation will support images, and images may not be important in many of those circumstances.

In addition, we should consider that significant parts of the website do not reside in qubes-doc. None of the pages listed in the top nav bar, nor the home page itself, for example, are in qubes-doc anymore (and I think this is as it should be, at least insofar as we consider this as a website).

But given this, a user who really wants a copy of the whole website (including both qubes-doc and qubes-attachment) can just do a submodule pull of qubesos.github.io.

[andrewdavidwong]

A more general question: Are we sure we want to do this? Doing so would significantly increase the size of qubes-doc. Since qubes-doc is currently just text files, it's only 671.5 kB, while qubes-attachment is 32.8 MB.

The benefit would be, as @marmarek pointed out, that it would be easier to make an offline copy of the documentation (including images), since there would only be one repo to clone. But what if someone wants a minimal, lightweight copy of just plain text documentation? Not every conceivable device and program which a user might use to view offline documentation will support images, and images may not be important in many of those circumstances.

In addition, we should consider that significant parts of the website do not reside in qubes-doc. None of the pages listed in the top nav bar, nor the home page itself, for example, are in qubes-doc anymore (and I think this is as it should be, at least insofar as we consider this as a website).

But given this, a user who really wants a copy of the whole website (including both qubes-doc and qubes-attachment) can just do a submodule pull of qubesos.github.io.

[marmarek]

On Tue, Sep 22, 2015 at 01:29:45PM -0700, Axon wrote:

A more general question: Are we sure we want to do this? Doing so would significantly increase the size of qubes-doc. Since qubes-doc is currently just text files, it's only 671.5 kB, while qubes-attachment is 32.8 MB.

The benefit would be, as @marmarek pointed out, that it would be easier to make an offline copy of the documentation (including images), since there would only be one repo to clone. But what if someone wants a minimal, lightweight copy of just plain text documentation? Not every conceivable device and program which a user might use to view offline documentation will support images, and images may not be important in many of those circumstances.

In addition, we should consider that significant parts of the website do not reside in qubes-doc. None of the pages listed in the top nav bar, nor the home page itself, for example, are in qubes-doc anymore (and I think this is as it should be, at least insofar as we consider this as a website).

But given this, a user who really wants a copy of the whole website (including both qubes-doc and qubes-attachment) can just do a submodule pull of qubesos.github.io.

Ok, so another question - is it possible to render just qubes-doc
repository into some browsable format (with working links)? I'm thinking
about HTML, but maybe it isn't the only option. Maybe we just need to
create another repository with qubes-doc and qubes-attachment as
submodules and a layout for documentation-only (so without top nav bar
etc).

Then it would still be simple to download just documentation and have it
stored offline. And if someone want text only version, he/she can
download qubes-doc alone.

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?

[marmarek]

On Tue, Sep 22, 2015 at 01:29:45PM -0700, Axon wrote:

A more general question: Are we sure we want to do this? Doing so would significantly increase the size of qubes-doc. Since qubes-doc is currently just text files, it's only 671.5 kB, while qubes-attachment is 32.8 MB.

The benefit would be, as @marmarek pointed out, that it would be easier to make an offline copy of the documentation (including images), since there would only be one repo to clone. But what if someone wants a minimal, lightweight copy of just plain text documentation? Not every conceivable device and program which a user might use to view offline documentation will support images, and images may not be important in many of those circumstances.

In addition, we should consider that significant parts of the website do not reside in qubes-doc. None of the pages listed in the top nav bar, nor the home page itself, for example, are in qubes-doc anymore (and I think this is as it should be, at least insofar as we consider this as a website).

But given this, a user who really wants a copy of the whole website (including both qubes-doc and qubes-attachment) can just do a submodule pull of qubesos.github.io.

Ok, so another question - is it possible to render just qubes-doc
repository into some browsable format (with working links)? I'm thinking
about HTML, but maybe it isn't the only option. Maybe we just need to
create another repository with qubes-doc and qubes-attachment as
submodules and a layout for documentation-only (so without top nav bar
etc).

Then it would still be simple to download just documentation and have it
stored offline. And if someone want text only version, he/she can
download qubes-doc alone.

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?

[andrewdavidwong]

Ok, so another question - is it possible to render just qubes-doc repository into some browsable format (with working links)? I'm thinking about HTML, but maybe it isn't the only option.

Well, it's pretty straightforward to convert .md to .html. For example, the discount package allows you to do this:

$ markdown SplitGpg.md > SplitGpg.html

And SplitGpg.html renders locally in the browser fine. External links also work fine since they include absolute URLs. However, getting relative URLs to work (for linking to other local pages) is a little trickier. I'm not sure what the best way to do that would be.

[andrewdavidwong]

Ok, so another question - is it possible to render just qubes-doc repository into some browsable format (with working links)? I'm thinking about HTML, but maybe it isn't the only option.

Well, it's pretty straightforward to convert .md to .html. For example, the discount package allows you to do this:

$ markdown SplitGpg.md > SplitGpg.html

And SplitGpg.html renders locally in the browser fine. External links also work fine since they include absolute URLs. However, getting relative URLs to work (for linking to other local pages) is a little trickier. I'm not sure what the best way to do that would be.

[marmarek]

I'm afraid using markdown directly wouldn't work because we use github
additions in some places. Or maybe I'm wrong about this?

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?

[marmarek]

I'm afraid using markdown directly wouldn't work because we use github
additions in some places. Or maybe I'm wrong about this?

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?

[andrewdavidwong]

You might be right. I'm not sure if any of the scripts convert to Github-flavored Markdown. When I write documentation, I try to just use plain Markdown for maximum compatibility.

[andrewdavidwong]

You might be right. I'm not sure if any of the scripts convert to Github-flavored Markdown. When I write documentation, I try to just use plain Markdown for maximum compatibility.

[andrewdavidwong]

I'm thinking about HTML, but maybe it isn't the only option.

We should also consider PDF (and, in particular, PDF/A), which is arguably the "gold standard" for immutable, self-contained documentation. (This also applies to #1019.)

Edit: Actually, now that I think about it, the best solution might be to use LaTeX to combine all the .md files into a single PDF with working internal links and embedded images.

[andrewdavidwong]

I'm thinking about HTML, but maybe it isn't the only option.

We should also consider PDF (and, in particular, PDF/A), which is arguably the "gold standard" for immutable, self-contained documentation. (This also applies to #1019.)

Edit: Actually, now that I think about it, the best solution might be to use LaTeX to combine all the .md files into a single PDF with working internal links and embedded images.

[marmarek]

On Wed, Sep 23, 2015 at 02:15:36AM -0700, Axon wrote:

I'm thinking about HTML, but maybe it isn't the only option.

We should also consider PDF, which is arguably the "gold standard" for immutable, self-contained documentation. (This also applies to #1019.)

Is it possible to have multiple pages (md files) in a single PDF, for
working links?

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?

[marmarek]

On Wed, Sep 23, 2015 at 02:15:36AM -0700, Axon wrote:

I'm thinking about HTML, but maybe it isn't the only option.

We should also consider PDF, which is arguably the "gold standard" for immutable, self-contained documentation. (This also applies to #1019.)

Is it possible to have multiple pages (md files) in a single PDF, for
working links?

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?

[marmarek]

On Wed, Sep 23, 2015 at 01:52:22AM -0700, Axon wrote:

You might be right. I'm not sure if any of the scripts convert to Github-flavored Markdown. When I write documentation, I try to just use plain Markdown for maximum compatibility.

pandoc supports Github-flavored Markdown (at least to some extent).

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?

[marmarek]

On Wed, Sep 23, 2015 at 01:52:22AM -0700, Axon wrote:

You might be right. I'm not sure if any of the scripts convert to Github-flavored Markdown. When I write documentation, I try to just use plain Markdown for maximum compatibility.

pandoc supports Github-flavored Markdown (at least to some extent).

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?

[andrewdavidwong]

Is it possible to have multiple pages (md files) in a single PDF, for working links?

Yes, it should be possible to to use LaTeX to combine all the .md files into a single PDF with working internal links and embedded images.

[andrewdavidwong]

Is it possible to have multiple pages (md files) in a single PDF, for working links?

Yes, it should be possible to to use LaTeX to combine all the .md files into a single PDF with working internal links and embedded images.

[andrewdavidwong]

@marmarek, since we've decided not to merge qubes-attachment into qubes-doc, IMHO this issue is now a duplicate of #1019.

[andrewdavidwong]

@marmarek, since we've decided not to merge qubes-attachment into qubes-doc, IMHO this issue is now a duplicate of #1019.

[marmarek]

Yes.

[marmarek]

Yes.