Comments (6)
heh, I wasted quite a lot of time here trying to figure out what exactly about our URLs was cool... turns out it's just the nomenclature from this article and just means "URLs must not change", otherwise everyone is unhappy.
from libxkbcommon.
@whot Sorry, I did not know it before Ran presented it to me. I adopted it (what a name), but I agree it is not self-explanatory. I edited the description of this issue.
It does not look Doxygen has a clear roadmap about this, because there are new differences between 1.9.7 and their master branch. They do intend to avoid these changes, but I doubt they have regression tests for that.
I could update our script to handle various Doxygen version, but the approach is still hacky.
I did try using other documentation generator. It seems Doxygen is best in class for code analysis. There are tools like Breathe that try to reuse Doxygen XML output, but then this is yet another tool to maintain in the pipeline.
Do you know/want another documentation generator, or should we fix our cool URIs script?
from libxkbcommon.
I agree it is not self-explanatory.
tbf, maybe the rest of the world may know it as "cool URLs" and I'm just not cool enough :)
I could update our script to handle various Doxygen version, but the approach is still hacky.
The only purpose for the documentation is to eventually show up on https://xkbcommon.org/ - I doubt there's a lot of use-cases that require it to be run and distributed locally (and do the URLS even matter then? probably not)
Which means that we could have a single CI job with a pinned version of doxygen that produces a tarball that @bluetech can upload on releases. At least until #326 becomes a thing :)
That pinned version could either be a manually built doxygen version or just use something that changes really slowly (i.e. Debian) so we only have to do these checks once every few years. AFAIK we don't really use any doxygen fanciness that requires keeping up-to-date with the latest version.
TLDR: using a stable debian with a (working) doxygen version to produce the docs is the least effort for years to come.
Thoughts?
from libxkbcommon.
I made the cool URIs optional in #351. The flag that activates them is intended to be set for the CI that will generate the doc with a pinned version of Doxygen.
from libxkbcommon.
While I approved #351, I'd say that my initial comment was about (trying to) avoid gratuitous URL changes on our side, because broken links are annoying. But if doxygen itself is being uncool, I think the battle is lost, not much to do except ask them to be cooler 😎. In some respects it might be better to just do the breakage as soon as possible, then it will be stable for longer in the future :)
from libxkbcommon.
OFF TOPIC
BTW, I just built with the new doxygen (updated by my package manager), and I get some warnings
warning: Tag 'HTML_TIMESTAMP' at line 43 of file '/home/ran/src/libxkbcommon/build/Doxyfile' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
/home/ran/src/libxkbcommon/doc/introduction-to-xkb.md:67: warning: unable to resolve reference to 'rule-file-format' for \ref command
/home/ran/src/libxkbcommon/doc/introduction-to-xkb.md:181: warning: unable to resolve reference to 'keymap-text-format-v1' for \ref command
/home/ran/src/libxkbcommon/doc/rules-format.md:10: warning: unable to resolve reference to 'xkb-intro' for \ref command
I'll take a look at them probably tomorrow (unless you beat me to it).
from libxkbcommon.
Related Issues (20)
- Support for pointer keys? HOT 8
- no usable option to activate horizontal number keys on Azerty keyboard HOT 2
- ! include line in rules file does not require a newline HOT 1
- LatchGroup action is not supported
- Types parser allows type definitions with garbage
- xkb_keysym_from_name returns upper case keysym for case-insensitive match in a few cases HOT 4
- Set Caps Lock to non-toggling without assigning it to Shift key, or make "last used layout" shortcut HOT 9
- Compose key does not always work HOT 11
- Documentation on how to create/install custom layouts needed HOT 16
- ABI break in 1.6.0 HOT 2
- 1.7.0: test suite fails in two units HOT 6
- Using my custom keyboard layouts doesn't work as expected when using `grp:alt_space_toggle` or `grp:win_space_toggle` HOT 4
- How to read used keysyms/keycodes for each modifier_map HOT 7
- meson.build script broke detection of --version-script support in GNU ld, as NetBSD uses HOT 3
- support multiple actions for a key per level HOT 2
- Please increment minor DSO version
- Feature Request: Add Halmak Keyboard Layout HOT 1
- rules: setxkbmap deals with empty component differently
- Crash on "Show Keyboard Layout" on GNOME HOT 8
- RMLVO: support for applying option on specific layout index
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from libxkbcommon.