-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256
Hi,
Thanks for the update. Don't worry about the schedule - while we do want
to finish this soon, it doesn't need to be yesterday.
On Tue, Oct 04, 2022 at 06:54:45AM +0200, mm wrote:
> Hello Marek, hello Andrew,
>
> I can have spare time starting Sunday to focus & reply.
>
> (Please, Marek, recall that i have pointed out mid September that I am out
> off the map
>
> basically from 15.09 till 8.10.)
>
> Nevertheless tried to fix different issues in some spare time, such as
> embedding videos, toctree etc.
>
> I will push my final version on master asap. (Still haven't gotten to the
> PR/merge/refactor), suggest to wait till Sunday.
>
> If that is not possible there are several issues to be considered:
>
> 0. please pay attention to config.toml and conf.py from master and the files
> in preparation.
>
> 1. which rst files are to be copied (there are 3 atm, since the most issues
> should be fixed via rstwriter2), which to be removed,
>
> different extensions to be configured such as redirects (I suggest leaving an
> empty hcl.rst (downloads etc) with a redirect, to be populated in a
>
> later stage via jinja scripting), new strikeout extension and new role, video
> directives, which markdown files are also to be copied
> - is doc.md the right one etc? latex documents are rendered correctly
> (toctree req)
I took toctree-example.rst and manually synced with recent doc.md. It
seems to work, including PDF version. The PDF could use explicit TOC at
the beginning, but it is in PDF metadata, so can be seen in the side
panel of PDF viewer.
> 2. !! Problem that should have a solution:
>
> f.ex.https://qubes-doc-rst.readthedocs.io/en/latest/user/troubleshooting/installation-troubleshooting.html
>
> in the sentence:
>
> "Here are the steps to fix this. Note that this allows sys-net and sys-usb to
> take complete control of the system, as described in the FAQ here:"
> there should be a cross reference to FAQ VT-d iommu section but is not. (with
> my version this is also a problem)
>
> Unfortunately the documentation (sphinx referencing via roles, perhaps the
> implementation?) is not saying anything how to handle punctuation with
> sections and cross ref with ref,
>
> so as of the moment I do not have an idea, apart from the basic stuff.
Yes, I hit similar issues elsewhere. Most of issues like this I fixed by
importing objects.inv and taking references from there (this is also
pushed to the PR), but there are still few corner cases like the noted
above. It seems '&' is handled differently by markdown and sphinx. All
the sphinx warnings fit for me on one screen, so I think those few
remaining cases can be fixed manually, there is no need to make the
converter perfect.
>
> I also tried explicit automatic labeling above each section with a directive
> (.. _id-of-section) - did not work out
>
> 3. different new files to be considered:
> f.e.x 2 versions of the privacy content, how to edit the documentation -
> markdown & rst version, visual style guide etc
Yes, I left some of them on the old site (with matching redirects), but
this needs to be sorted out.
> 4. what is done so far on master
>
> -- video directives
>
> -- toctree index, notes, schedules, upgrade, how to restore
>
> -- section cross referencing small fixes
>
> -- svg conversion to png for selected files and replacement in rst docs
>
> -- convert leftover markdown links in rst files
>
> -- markdown redirects
>
> -- added directives for warning & note (can be used also for indicating
> translated content)
> -- anything i forgot
>
> 5. weblate - localization platform should be the way to go imho (sry not a
> big fan of transifex rn, weblate is OS etc,
> some more objective analysis will follow), there are several issues to be
> clarified, wip, tails guys need good questions to work with
> - will be done on sunday
> 6. anything i forgot, did not address, mentioned too briefly or not clarified
> i will address on sun
> (if it is still needed)
>
> all the best,
> m
>
> On 10/2/22 18:24, Marek Marczykowski-Górecki wrote:
> > On Tue, Sep 27, 2022 at 01:15:56AM +0200, Marek Marczykowski-Górecki
> > wrote:
> > > On Mon, Sep 26, 2022 at 11:33:22PM +0200, mm wrote:
> > >> Hi Marek,
> > >>
> > >>
> > >> On 9/26/22 00:01, Marek Marczykowski-Górecki wrote:
> > >>> Hi M,
> > >>>
> > >>> In fact, I'm working on translation-utilz right now too. Marta used
> > her
> > >>> google-foo and found this gem:
> > >>> https://github.com/SamWilsn/docutils-rst-writer
> > >>>
> > >> this looks very nice!! :) Thanks Marta! :)
> > >>
> > >>> So, I replaced most of the qubesrstwriter2.py with just this thing and
> > >>> it's almost flawless (especially tables, images etc work out of the
> > >>> box).
> > >>
> > >> OK, thanks for the PR, I'll merge into and get rid of the obsolete
> > stuff
> > >> from my branch this days.
> > >>
> > >> I have some weird customized fixes all over, but
