Here's an update on my current work and plans since several people have
asked me about it. This is a long email.
*
JavaScript*
I've dropped the jQuery UI dependency and I'd like to keep it that way.
We don't benefit a lot from JavaScript UI libraries because our main
components are pre-rendered. The full jQuery UI is quite heavy and we don't
to pay that cost for the very few features we were using. If we end up
using it again, can we please only include the features we need?
I've consolidated some of our other JavaScript resources into common.js
to reduce the number of javascript files we need to load. I've also moved
all JavaScript to the bottom so they don't block the loading of the
website. Some very basic tests showed that this improved my load time by
200ms.
*Autocomplete*
The search autocomplete bugs are the main reason the current responsive
branch is not merged into master. It honestly needs to be rewritten from
scratch because the HTML, CSS and JavaScript were all quite buggy. It was
also previously using jQuery UI which I've now removed. This means that for
now, the responsive branch doesn't have autocomplete enabled at all.
*Syntax Highlighting*
* *Better syntax highlighting for the docs is an often-request
"feature". For a while I just dismissed it as low-priority but the more I
think about it the more important I think it is. Two major findings:
1. PhD already has a fairly easy way to change the syntax highlighting
mechanism.
2. User-contributed notes are currently post-processed at runtime to
convert the styles to CSS classes.
I'm working on a PhD syntax highlighter that will mark up the resulting
html with classes instead of styles. This allows for easier customization
for how the markup is displayed. The user-contributed notes should also be
able to reuse the highlighter.
*Theming and Stylesheets*
Another often requested "feature" is a dark UI theme. I definitely
think we should focus our efforts on producing a high-quality primary
theme; I won't be working on a dark UI anytime soon. However, the
stylesheets are a mess and it's hard to know where a style should live.
Currently we have bootstrap.css, theme.css and docs.css that are included
on every page. Since I need to improve the stylesheet organization I
figured I might as well lay the groundwork to make switching themes easier
while I am moving things around. I propose:
- base.css: This includes the framing of the website. Basically anything
besides color.
- theme.css: This is where all the color-related styles live.
These changes should make maintenance easier and allow for theme swapping.
It will also boost website performance by a bit; we don't want to slow down
in the rework.
*PhD Rendering*
Currently the section headings display above the "box" that contains
the section. In the HTML the heading is actually a part of the container
and there is no separation between the heading and the content so we have
to use margins to hack this together. I've looked into alternative ways of
achieving this effect but haven't found another way without modifying the
HTML. It also causes problems with the way our new fixed header interacts
with anchors (#refsect-*). I'd like to change PhD to add simple div around
content that doesn't include the header. This will make the display problem
go away and allow us to fix the menu-anchor interaction.
We also have some JavaScript that goes through and removes p tags that
only contain whitespace. This is necessary because PhD does a simple
mapping from docbook para tags to html p tags, but para tags can contain
lists and p tags cannot. Browsers fix this issue by ending the p tag and
then reopening it after the list. However, that causes odd spacing around
the website. They cannot be targeted with CSS :empty rules because they are
not actually empty. If someone who knows PhD would like something to work
on then this would help out a bit and is definitely an improvement for PhD.
