This converts the code snippets to the alternate block definition and
adds language hints to enable syntax highlighting for compatible parsers
(such as on the GitHub page).
Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>
The previous index.html was scary and the most useful links were
at the bottom. This commit fixes that.
It also adds an image of the default config with some labels to name
all visible components.
This will break some existing links, but oh well, it isn't the first
time and some websites cannot render URLs with spaces in them. This
means external references to some of the input doc are currently
impossible.
From now on, all core object will have their own rules. `awful.rules`
hardcodes some client specific code. All `rules` module have some form
of class specific code. This code will now be part of a new module
called `ruled`. Since a year or so, a lot of work has been done to
refactor the rules on top of the shared `gears.matcher` class. This way
there wont be as much duplication.
This has to be in its own commit otherwise Travis will fail. This
is because it will keep the file in the build directory when
iterating all commits. Then `ldoc` will fail because the file doesn't
have documentation. If `config.ld` is updated first, then it will
fail because `ruled/init.lua` doesn't exist yet. When it is done
in a separate commit, then `config.ld` is already updated and comes
with `init.lua`.
This also pulls in part of the permission framework to ensure
backward compatibility is kept.
`awful.autofocus` was always weird. It is a module part of `awful`,
but it was never part of `awful` `init.lua`. Rather, `rc.lua` was
the sole place it was used. It behave exactly like a request, but
predate them by years. As I cleanup the request:: API before the
permissions API gets formalized, this has to be fixed now.
It isn't deprecated in this commit because it makes too many tests
fail. Another pull request will solve that by adding the "API level"
concept to AwesomeWM so I can change the behavior without breaking
existing configs. With that, the behavior of `autofocus` will be
enabled by default with the permissions to disable it.
The default `rc.lua` was using the focus/unfocus signals to set
the border color along with `awful.rules`. This logic block was
no longer aligned with the rest of `rc.lua` since it was
the only place where `beautiful` variables where only used by
`rc.lua`.
On top of this, the new request handler also has extra contexts
for the urgent and floating/maximixed use cases. So it can be used
by themes to implement much smarter borders than just focus based
ones. They were previously limited by the fact most of the
(un-monkey-patchable) logic was in `rc.lua`.
Note that this commit also shuffle the awful.rules order between
the titlebar and the border and changes the tests accordignly.
After some consideration, I came to the conclusion the previous
behavior was bogus and the fact that the placement tests required
to know about the titlebar height is simply a proof of that. The
change was required in this commit because since the border is no
longer in the default rules, a new buggy edge case surfaced.
They currently fit the general concept of a `request::` in the sense
that they are not property related and have "request handlers".
The commit also add deprecation for signals.
The reason for this fits within the larger standardization project.
Non-namespaced signals will eventually be renamed. This has started
a long time ago.
What is old is new again. Once upon a time, there was a `startup`
parameter to the `manage` signal. It is now back in the form of
a context.
Finally, this commit removes the `manage` section of `rc.lua`. It no
longer did anything worthy of being in the config. Each of its
important parts have been moved out over the years and the last
remaining bit is always required anyway. The code has been moved
to `client.lua`.
It is optional for now, but maybe in the future we can make
it mandatory. It will allow to have some "New!", "Not released"
messages or something in the doc. That would allow us to share
most of the doc between the stable and git versions.
They do nothing for now, but once we are done adding them to
everything, they will replace the old `@deprecated` family of
type-tags.
They carry more information such as when it was removed and why.
Cross-referenced with the @version, we can infer the deprecation
status based on the current release rather than a boolean
"deprecated or not deprecated".
* Add `@inheritedproperty`, `@inheritedmethod` and `@inheritedsignal` ldoc tags to specify inherited members in the documentation,
* These new tags create their own section in the rendered documentation,
* Implemente these tags for `docs/common/object.ldoc` and `docs/common/widget.ldoc`.
First of all, yes, JavaScript in the doc. I don't like this either.
The reason is that the new sections are super useful *when you need
them*. However, in practice, that's rare. So better not make the
signal to noise ratio worst. Future commit will introduce an
auto-generated summary of what's hidden.
This allows to state that this variable has a equivalent beautiful
variable named using the usual conventions. It will generate all
the boilerplate magically and also takes optional fallback variable
names.
So, now ldoc is implemented within ldoc, great!
This is done to allow new custom tags to have the same power and
expressivness as built in ones. This way we can express signals
and theme variables correctly.
get_children's return value should not be called "The". That was a
mistake because ldoc requires a name for return values and parameters.
If a name isn't provided, it thinks the first word of the description
is the name.
It might not be the most pretty of change, but it works. With this
change, it is possible to have multiple "things" in the "same"
section having the "same" name.
This allows for C/C++ style functions with the same name but different
signatures. Lua doesn't handle this well, so it should usually be
avoided. However, constructors might be a valid exception. Most older
widget (and object) constructors have multiple random argument while
newer one use `args`. Deprecating the old ones for the sake of
standardization might be a bit too much for users upgrading from v3.5.
Given the only reason all of those deprecation would happen is because
"its pretty that way", then lets allow 2 constructors and avoid outrage.
This is done now because a lot of code in `lib/` add buttons by manually
extracting buttons from awful.button. Instead of adding ugly code to
prevent using the legacy API, do this.
The reason for this is that as more of CAPI is brought in line with the
current API guidelines, it is more and more likely the tests will hit
APIs shims (either to test them or because the prototype remains the
same and only the implementation moved to Lua).
Add `dpi.lua` to config.ld even if it isn't added yet. This is
because the way the test run has it cached in the build dir. A full
rebuild would take too long and timeout on travis for semi-large PRs.
Since commit 3295e9f33d, the imagebox tries to use libRSVG via
lgi.Rsvg to load SVG files without rasterising them immediately.
Instead, they are directly drawn at the expected size.
Signed-off-by: Uli Schlachter <psychon@znc.in>
For dubious reasons, ldoc uses the human readable name for the URLs
instead of the machine readable one. If the name has multiple words,
this causes the URLs to have spaces or %20 in them.
This commits remove all spaces from the "kinds" and then use `:gsub()`
in the template to convert underscores to spaces.
**WARNING** This breaks all URLs again. But this is necessary to prevent
broken links when the user paste them with spaces instead of %20.
Rather that abusing of how the arguments are displayed to convey the
type, add native support.
It still uses the @param for the doc, so this doesn't cause a million
little noisy changes, but the rendered HTML now have a real section for
the type. This is added to both the summary and the expanded description.
Additionally, if the type has a description string, a second is added.
This way their name doesn't get mangle by the broken magic. It will also
eventually allow to `error()` in the template when the implicit
`@function` is used.
This commit also fixes a large number of issues found while
proof-reading everything.
ldoc has a magical `@classmod` module type which tries to detect
what is a method and what is a static function. It fails about as
often as it works. This commit makes everything explicit to remove
such issues.
Fixes#2640
Ref #1373
The module names for also have their alias. The commit also remove 2
deprecated module that were forgotton in the previous "get rid of the
deprecated modules in the doc" PR.
It worked fine for the table in the header, but the name is also used in
the "main" documentation below. This caused the while text to be within
the "<a>" section.
It was displayed for most sections, but not the functions. This is
problem when the doc already contains a bullet list just before the
parameter section. The two looked as if they were a single list.
There was some issues like `gears.shape.circle` being called
`module.circle`.
There is also a disparity between how the constructor and "normal"
functions are called.
This commit attempts to force everything to have the full module name.
Previously, there was some `module:foo()` or `gears.object:foo()`
because the doc used the "raw" name and/or, in some undefined and
race condition prone (due to `pairs()` order), the formatted
"classmod" name.
Now, just display `:foo()` and be done with it.
This library allows to get a human-readable string describing X11
requests, events, and errors. We now use this library to pretty-print
X11 errors if we get any.
To test this code, I added the following two lines to AwesomeWM so that
X11 errors are generated:
xcb_set_input_focus(globalconf.connection, 42, 42, 42);
xcb_randr_set_output_primary(globalconf.connection,
globalconf.screen->root, 42);
Output without xcb-errors:
X error: request=SetInputFocus (major 42, minor 0), error=BadValue (2)
X error: request=(null) (major 140, minor 30), error=(null) (147)
Output with xcb-errors:
X error: request=SetInputFocus (major 42, minor 0), error=Value (2)
X error: request=RandR-SetOutputPrimary (major 140, minor 30), error=RandR-BadOutput (147)
Signed-off-by: Uli Schlachter <psychon@znc.in>
The commit also re-work the build target so if the file are deleted,
then they are created again. Using `file(COPY ...)` and
`file(MAKE_DIRECTORY ...)` as done previously caused some file to be out
of date or not being regenerated at all.
This commit also fixes some broken target that depended on `file(` and
`configure_file` CMake command not being part of any target.
Fix#2342
Until now there wasn't much documentation available about how to use
these properties. With the new work on `awful.spawn` that rely more and
more on `awful.rules` integration, it is worth fixing.
This commit add a new documentation section and a future commit will
aggregate them to generate an index.
Lucas Schwiderski
Jonas Belouadi
Emmanuel Lepage Vallée
Aire-One
Unai
Michael
Matthew Wild
Uli Schlachter
feltcat
Jordan Christiansen
actionless
Xinhao Yuan
Uli Schlachter
mergify[bot]
DrEuler
Alphonse Mariya
Daniel Hahler
Sergey Vlasov
Daniel Hahler