Open erikmd opened 2 years ago
Here is a screenshot of what we can expect:
On second thought, it seems with this current PR version, the user would need to write a ./docutils.conf
with:
[html5 writer]
section_self_link: yes
@cpitclaudel What source file should be edited in alectryon to make this option a default? (if you don't disagree to do so (but I don't see any drawback that it could cause))
Thanks, looks good! Two questions:
Do we really want to change the default to html5? I think it's OK for people to pick that manually. There's a command line flag for it.
Did you take the CSS from the default stylesheet?
What source file should be edited in alectryon to make this option a default?
Should we make it the default? I'd prefer to not deviate too much from plain docutils. If we must it can be done in docutils.py, in the custom writer inherited from html5writer, I think. The advantage of doing it there is that it can still be overwritten by a setting.
Hi @cpitclaudel
Do we really want to change the default to html5?
IMHO, I'd vote for it. Indeed:
section_self_link
the default (see below), using the html5 writer
is the only requirement AFAIK.Did you take the CSS from the default stylesheet?
Yes! but I improved it a bit → adding the text-decoration:none
element to ensure there's no ugly bar below the anchor đź”—.
Should we make it the default? I'd prefer to not deviate too much from plain docutils.
OK, I see what you mean, but:
However, regarding the implementation, I'm not sure I could extend/refine this PR as quickly as you could…
so let me know if you don't have time and I'll try to push new commits at some point, otherwise feel free to amend my PR!
(using git prw
or so for example, or opening a new PR)
@cpitclaudel friendly ping :) WDYT?
Hi @cpitclaudel, how are you? would you have the time to help integrating this contribution?
AFAIAC, this will be a very important enhancement for our Alectryon-based courses.
Hi @erikmd, sorry for the delay :'(
Here's the issue: docutils HTML5 compiler does a lot of things differently from the HTML4 one, so people who just recompile an existing document with custom stylesheets will see breakage. I don't know when/whether docutils will switch, but I'm not sure we should until they do.
You say it will enhance courses, but why not use it already? IIUC all you need is to add the additional flag and add the short CSS to your own stylesheets?
Sorry if I missed something (and sorry I took so look to reply)
Hi @cpitclaudel, no worries and thanks for your reply!
Some thoughts:
You say it will enhance courses, but why not use it already? IIUC all you need is to add the additional flag and add the short CSS to your own stylesheets?
that's a good point :) but we did so already:
https://github.com/pfitaxel/tapfa-coq-alectryon/blob/master/docutils.conf
so the main goal of this PR was to let more users to benefit from this feature… including users that are not aware of the docutils internals.
And even I agree with you that backward-compatibility is paramount, I guess this PR (which is incomplete BTW, so in draft mode, cf. this comment) should not incur "regressions"… WDYT?
ping @cpitclaudel, would you have some time to help me improve/finalize this PR if you agree with my last comments?
Sorry, I had lost track of this. So there are three things here:
settings_default_overrides
in HtmlWriter in docutils.py (ideally only for HTML5 I think)
I recently noticed that despite the availability of this new feature in docutils: https://sourceforge.net/p/docutils/feature-requests/28/ (which BTW can only be enabled in HTML5), the feature requested in cpitclaudel/alectryon#19 was not yet possible in alectryon.
So, this PR makes it possible to benefit from this feature in Alectryon as well by default.
Cc @cpitclaudel