Documentation - Githubissues

It seems that the documentation for this project isn't getting updated and maintained.

generated by LDoc 1.4.6Last updated 2030-01-01 00:00:00 - https://awesomewm.org/apidoc/theme_related_libraries/beautiful.html

Also it seems that no one has actually taken the time to write some tutorials or otherwise explained the workings of awesome. I don't want to have to be intricately knowledgeable about awesome in order to know how to e.g. change fonts. The problem is that it's a reference in a sub-page without redirection other than it's 'arbitrary' name of - in this example - beautiful.

I want a search please. That is in no way too much to ask for extensive documentation.

Where are all the contributors on the website? There have been so many on the GitHub page but it's not reflected anywhere. It also seems contributions ended in 2014. If people are still contributing you go 2014-current or programmatically update every year and check if they have contributed that year.

Are you manually updating pages/information and have no way of automatically checking if what you're saying is correct? How does updating contributors and more importantly updating API docs work in Awesome?

Several of the links you're using under the recipes are either outdated, doesn't exist or are referencing older versions of Awesome. That makes the project itself seem dead. Let's take Tyrannical:

Finally, Awesome 4.0 introduces support for adding and removing screen at runtime. Therefor, being able to expand and contract the tag set dynamically is finally possible. Being able to support the use case where a laptop is optionally plugged to an external monitor will be implemented once feature parity has been achieved. Future: My first attempt at implementing dynamic layouts failed back in 2012, but for a year I have been using a new implementation. This isn't expected to land in Awesome anytime soon. But once it does, Tyrannical will gain the ability to describe whole dynamic layouts instead of "just" its tag.

What does it mean? Because I don't see anything about this anywhere. Also, Tyrannical itself is providing another way of accessing awesome.rules in it's example config. I don't even know the rules let alone best practices for calling other modules, so I have no way of knowing if I should use Tyrannical's (code frequency) way or the awesome way (since I want to apply Tyrannical, which paradigm should I use)

The short of the long is that this project seems dead, I want confirmation if you're looking to improve the project or if this will continue as a clearly hobby/side project.

To make my point even clearer, I'd like to notice I'm not good at C with my only exposure to it being DWM. I still find DWM easier to manage than awesome; all the patches have proper descriptions and the code is readable. Awesome obfuscates so many things, it simply has to clearly state how to configure it (without a user having to 1) know every module-name within awesome 1.1) go to the website and click at least 3 times 1.2) probably not get a better description than an implementation and direct explanation e.g: wallpaper | string or gears.surface | The wallpaper path.

How do I specify fallback fonts? I want a main font for use in the statusbar, windows etc. then a font specifically for x program. If my main font does not support a character I'd love to be able to specify several fallback fonts to use, how would I do that?

The above question should be answerable by going to the documentation, but it isn't.. at least not with my current understanding of awesome and it's documentation (bear in mind I actually need knowledge of the awesome docs in order to get some use out of it.

Sure I can configure everything, care to share any knowledge of how to do that or are you keeping that for yourself and let people learn to invent the wheel if they wan't to change the defaults of this highly configurable dm?

Here are some things I've been looking for:

How is awesome built (what, why, how, thoughts)
Guides: learn how e.g tags/font/cairo/widget/beautiful work with this simple guide with many explanations and reasoning
Contributors
Best practices for X; best way to configure X; Common pitfalls for X; Understanding X (x being beautiful or gears etc.) basically a short paper describing what X is, why it is used and how to change the defaults, which defaults you'd want to change when using X; just talk more about stuff than:
```
Module: beautiful
Theme library. 
Info:
Copyright: 2008-2009 Damien Leone, Julien Danjou
Author: Damien Leone <damien.leone@gmail.com>,Julien Danjou <julien@danjou.info>
```
And here is the entire rest of the reference unfit for human reading and comprehension

The documentation is really lackluster on anything else than the actual reference which isn't actually helpful with descriptions like "this is x" and "x does y thing" e.g what the difference on gen_logo() and awesome_icon() because they both define sizes and everything, but have to be used together for a result. Which color overrides the other and why do I have to set it several times? REASONS

generated by LDoc 1.4.6Last updated 2030-01-01 00:00:00 - https://awesomewm.org/apidoc/theme_related_libraries/beautiful.html

This timestamp is for reproducible builds / a cleaner git history. It is set as a fixed date here (SOURCE_DATE_EPOCH): https://github.com/awesomeWM/awesome/blob/5cdd960669ed05fa46face3995afd7140f246322/.travis.yml#L86 In case you missed it: This timestamp is almost 10 years into the future. This is not from the beginning of the year.

I want a search please. That is in no way too much to ask for extensive documentation.

Okay, please tell us how to do get a search into a static website hosted on github pages (gh-pages) that is built with ldoc.

Where are all the contributors on the website?

Contributors to what? To awesome? They are listed here, but I feel like I am misunderstanding the question: https://github.com/awesomeWM/awesome/graphs/contributors A link to that page is seen here: https://awesomewm.org/community/

It also seems contributions ended in 2014. If people are still contributing you go 2014-current or programmatically update every year and check if they have contributed that year.

Sorry, but what are you talking about? Where does this "2014" come from?

Are you manually updating pages/information and have no way of automatically checking if what you're saying is correct? How does updating contributors and more importantly updating API docs work in Awesome?

It's automated. Each Travis build runs the following shell script (on Travis): https://github.com/awesomeWM/awesome/blob/master/build-utils/travis-apidoc.sh That pushes a new version of the generated docs here: https://github.com/awesomeWM/awesomeWM.github.io The website itself is found here: https://github.com/awesomeWM/awesome-www It is also automatically updated via Travis after new commits to the master branch.

What does it mean? Because I don't see anything about this anywhere.

Uhm. Do I understand correctly that you are proposing that the link to Tyrannical should just be removed?

if you're looking to improve the project or if this will continue as a clearly hobby/side project

I fail to see that one of these options excludes the other. AwesomeWM always has been a hobby/side project. No one is making any money with it.

How do I specify fallback fonts?

Honest answer: I do not know that, too. Something with Pango, I guess...

Either have a last updated be updated when there's updates or at least don't show it to everyone (the only effect is confusing and questioning the abilities of whoever made a clear mistake). Why use a wm if its website isn't even working properly, I mean, what does that say about the general quality of the code to an outsider? I can see the last edited part is working on most other pages (actually haven't found the placeholder a lot of places) so it seems to be an easy fix.

I suggest not to host extensive documentation that would need search on gh-pages, as they're not made for really big projects that has a lot of moving parts(gears, beautiful etc.). It's made for small projects and generally static pages(blogs, I am me pages etc.), for documentation on an on-going project this size, you'd want to use one of the many free open source solutions that exists. There's countless options that support open source and gives their product for free e.g. https://www.elastic.co/subscriptions (under self managed). I suggest using Vercel for deployment, as their free plan should be enough and the service is amazing.

To put it bluntly: ldoc is not good enough in its current state, it's only made for references (not oss project documentation), and the awesomewm website looks extremely outdated and stuff like this is not acceptable for a project that has lived for so long. The website and documentation, lookup and contributing process is incredibly unoptimized and as an end-user not easy to figure out.

Now I'd like to take a second to say that I'm not mad or trying to attack anyone here, I'm looking at standards, former experience and have a hard time thinking that the project looks like it was born a few months ago despite being several years old, the documentation doesn't say "I've been here for 10 years!", neither does the website(maybe in theming but that's not on the table for this discussion, only content).

I think everybody involved has done an amazing job of contributing to awesomewm and are probably very talented to do so. I appreciate all the hard work, sweat, blood & tears that has gone into this project and hope others share my confusion & vision for awesomewm. Thank you very much, and no matter how hard I'm hitting you in the head - it's because you already made something amazing (not because it could be)... I just want it to be awesomer!

I can also recommend Transifex for translations (it is truly amazing they have a free plan for OSS) and CodeClimate for automated code checks and other goodies.

You could keep using ldoc which seems to be dead and lackluster in features, that wouldn't be a problem besides the continuous updates needed to keep a website working with the ever-changing web stack. I can't stress enough how a reference and documentation are different things. The docs website is currently (an arbitrary) 95% reference and 5% documentation, there is a few guides yes, but that's not even documentation, it's guides (not explanations or reasoning, but steps/a process to execute). Look at https://awesomewm.org/apidoc/documentation/02-contributing.md.html and tell me the website is perfectly fine as-is.

For documenting the inner workings of awesome, the reasoning, why X decision was made, how to do X, which problems people have encountered and how they fixed them, guides, advanced guides, how to use awesome in X environment, and so much more that is nothing but text (not references to code): I suggest the up-and-comming https://github.com/Requarks/wiki. I haven't tried it but it seems promising and 100% able to accommodate the needs of awesomewm documentation.

These contributors: https://awesomewm.org/doc/api/documentation/00-authors.md.html the latest date written on that page (besides the future) is 2014. As i said before, writing 2014- seems like person contributed in 2014 only and someone forgot to put the rest which could be the same year or 20 years later. You go 2014-Current or 2014-xxxx.

It's automated. Each Travis build runs the following shell script (on Travis): https://github.com/awesomeWM/awesome/blob/master/build-utils/travis-apidoc.sh That pushes a new version of the generated docs here: https://github.com/awesomeWM/awesomeWM.github.io The website itself is found here: https://github.com/awesomeWM/awesome-www It is also automatically updated via Travis after new commits to the master branch.

^ Why not disclose this to possible contributors? https://github.com/awesomeWM/awesome/blob/master/docs/02-contributing.md There's so much information missing from here that a new contributor would like to know about.

Regarding Tyrannical, it seems it is useless now? There was some news "Parts of Tyrannical were merged into AwesomeWM 4.3 and it will make everything more reliable.", I see the person who made Tyrannical is now contributing directly to awesomewm. Tyrannical hasn't been updated for long but is that because it's done, it's merged into awesome or what? I have no idea if Tyrannical is implemented in awesomewm already, only partly or what has happened. There's a giant lack of transparency in regards to this. I've seen movements from awesome to handle tags better but is that done to replace Tyrannical or does it still extend the functionality? How do I figure it out besides meticulously going through commits? It's like someone just stopped informing of what is going on, which is detrimental to the possibility of new contributors.

I fail to see that one of these options excludes the other. AwesomeWM always has been a hobby/side project. No one is making any money with it.

I'm trying to say that most text looks like someone wrote something once and it hasn't been touched since. The project engagement seems to consist of already engaged people (from a simpler time) or people like me who likes to suffer. I can, again, direct you to countless open source projects that are doing incredibly fine, perhaps you know some yourself; try and compare those to awesomewm. E.g.: VS Code, NextJS, Material-UI, Wikimedia.

Not being sponsored or otherwise engaged upon by the community is sad to me. It makes me want to fork the project to get sponsors and engage contributors, in order to make an amazing project people want to be a part of and engaged in. That would need a complete overhaul of the documentation though. Just having some git templates and updating the contributing should be a good start.

I can, one more time, give you an extremely long list of open-source projects that exists independently but are still sponsored and donated to by people & orgs. I don't think it's a bad thing to keep people engaged with money and a super awesome community where it's easy to get started contributing. If I were more inclined to contribute, I'd immediately add the fallback font explanation to the documentation (I don't know where it would be best to put though, in the middle if the awesomerc page? Idk)

My thought looking at AwesomeWM is the possibility of being a default choice wm because it is so extensible (and quite stable from my experience), I'm sure others have noticed it too and thought they would have acted upon it in some way or another.

I believe a lot of people would like (and use) awesomewm if the introduction and documentation was more human-friendly.

In regards to the fallback font, if pango is the only thing being used (to my knowledge it is) all I had to do was:

know what function is called from awesome to set font 1.1 look at the reference for that function
Read the last part of the explanation for the reference

In some uses of PangoFontDescription, it is also possible to use a comma separated list of family names for this field.

So I tried a comma separated list, which worked quite good, but not even Pango describes what is actually going on, only that it sometimes is possible.

I was looking through issues of the project and saw someone wanting to update the website.

Can you please describe every single demand of awesomewm website and documentation and a bit of reason why those choices are made? Because it seems to be very un-inclusive for very personal reasons. The project states "any people dealing with every day computing tasks and who want to have fine-grained control on their graphical environment." which is by definition a normal user that shouldn't have to read source code to change stuff or get it working... or understanding it for that matter. Update the project description if this isn't true. There are people out there who accepts and work with, and use JS, because it enhances the experience, those same people could still have a lot of alignment with awesomewm and want to rice their computer (I think that would be the majority). I think few people like being completely locked down and actually appreciate many options (with sane defaults), I know for a fact that a lot of people like customizing things because it is fun, entertaining and can be pretty; those people want fine-grained control right? They also don't give any flying fucks about JS, they just want to access a website that's easy to use and navigate. They just want awesome, not some ideology about scripting for the web.

Did you know GitHub is owned my Microsoft? You shouldn't host anything here if you're against the JS revolution or whatever makes it so bad, you should self-host the project and use something like GitLab right? I'm a bit confused why JS is soooo bad but GitHub isn't, even though your project & website is literally at the whim of Microsoft (https://en.wikipedia.org/wiki/Embrace,_extend,_and_extinguish) - they could close the service tomorrow. If it's about security, update yourself, there's very specific cases where it's viable to think about being secure, but in most use-cases for websites it simply doesn't apply. You do your normal web security and your server is safe along with the user who is already sandboxing the webpage in a tab in another sandbox. Web browsers (and computers) are so insanely powerful nowadays, and the tech world has moved from jquery 10 years ago to SPA,PWA and websites made with dynamic SSG today. Most arguments made against JS are either applicable to every situation of the like (e.g scripting for programs) or don't hold true with today's tech.

I'd like to drop my two cents here too. I am using awesome WM now aroundish 10 years and while I would agree that there were times I had a hard time with the documentation (or the page, e.g. the missing responsiveness already annoyed me a lot of times when I wanted to look up APIs for ideas on my phone), I think a couple of comparison drawn in this thread here are a bit off.

I can, again, direct you to countless open source projects that are doing incredibly fine [...]

All those mentioned open source projects are backed by companies worth millions, billions and even trillions (in fact the smallest mentioned was next.js, backed by Vercel, which has "only" a series A 21 million founding and employing hundreds or thousands of employees. This is a significant difference from (as @psychon stated) a hobby/side project, that is not targeted to ever turn into a company.

And I think that's just a very difference in what you want that project to become. Even if that project could get some larger sponsors to give financial support (let's just assume it would be possible), it doesn't mean that any of the current maintainers actually WANTS to cut down on their regular job to maintain this project even with financial founding available.

If people from the community want to improve this documentation and want to spend that time, I wonder if it might make sense to break down potential improvements into smaller steps so people can pick them up and spend the time into it. But "expecting" anyone from the maintainers to do any specific kind of work or spend time among what they want to spend for a hobby/side project won't get us anywhere.

Also I am not sure if everyone here has the same perception of what AwesomeWM is (should be):

My thought looking at AwesomeWM is the possibility of being a default choice wm because it is so extensible (and quite stable from my experience),

I would never see awesome wm being a "default choice", but rather a very professional tool if you need THAT level of fine grained control that even i3 with it's configuration approach won't be able to give you anymore. That's also how I always understood the motto you quoted above:

It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on their graphical environment.

and also especially a bit further down:

To achieve this goal, awesome has been designed as a framework window manager.

This is for me a clear statement: this gives you fine-grained control with all the drawbacks of "it's just a framework, not a ready to go tool", so expect you'll need a lot of deep-dives to potentially even get basic stuff working.

I have the feeling for people who run just the default configuration and want to make minor tweaks, that's not even the right tool and they'd be better off with something like i3. I always thought this is more a tool if you really want to "build your own window manager", but don't want to mess with C or too deep understanding of several X standards.

btw regarding misleading copyright/author fields in the docs -- i think this problem was raised before few times

i suggest either to just remove it or to replace those two fields to a single link to github commit log for the appropriate file

@timroes Thanks for your input. First, I'd like to address the 'other open-source projects' part. I used some examples of projects of which one could draw inspiration. For more realistic comparisons, Material-UI is definitively a good comparison (project size, no initial corporate backing, etc.). I can find a more directly comparable list and spend some hours doing work in that regard if anyone would like that. I can mention FSF as a never corporate project that still has some structure to it.

And I think that's just a very difference in what you want that project to become. Even if that project could get some larger sponsors to give financial support (let's just assume it would be possible), it doesn't mean that any of the current maintainers actually WANTS to cut down on their regular job to maintain this project even with financial founding available.

Well, I guess that's where my whole 'forking the project' comes to fruition. If the maintainers keep being (from my outlook) very disinterested in enabling more collaboration and keeping the current state of the project, I might as well start it anew applying best practices and drawing from experience from the best projects.

I have an easier time using C (which I don't work with & have used about 5h total) to upgrade (patch) DWM than I have when navigating the awesomewm documentation and making configuration changes:

I have the feeling for people who run just the default configuration and want to make minor tweaks, that's not even the right tool, and they'd be better off with something like i3. I always thought this is more a tool if you really want to "build your own window manager," but don't want to mess with C or too deep understanding of several X standards.

That is the biggest reason for my less than positive stance. I have an easier time reading source code in a language I don't understand, than navigating documentation. The experience as mentioned happens very rarely and has - to me - historically been an effect of less than ideal documentation. I'd like to note that I know a lot of programming concepts, so, e.g. LUA and C is mostly a matter of syntax to me (I usually catch the gist of code by reading it); this might be different from others.

I would never see awesome wm being a "default choice", but rather a very professional tool if you need THAT level of fine-grained control that even i3 with its configuration approach won't be able to give you any more. That's also how I always understood the motto you quoted above: "It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on their graphical environment." This is for me a clear statement: this gives you fine-grained control with all the drawbacks of "it's just a framework, not a ready to go tool", so expect you'll need a lot of deep-dives to potentially even get basic stuff working.

Let me pick the part of the sentence that matters to what I'm saying: "any people dealing with every day computing tasks and who want to have fine-grained control on their graphical environment"

I agree with what you state until we get to the 'any people dealing with every day computing tasks' part, which refers to people having daily tasks involving a computer (e.g. Word, playing Flappy Bird, running cow-say). Saying otherwise would be arguing the meaning of the words/part of the sentence. Now for "who want to have fine-grained control on their graphical environment" is power users, developers, and any people who want fine-grained control over their GUI.

Here is where I'm getting worked up. Because it seems there is a significant disparity between what the project was and what it has become. Today, computing task newbies are asking the same questions (that is avoided by writing excellent documentation with references and reasoning) again and again, answered by maintainers of the project again and again. Why are things not improving in this regard? I'm not here to pat anyone on the back; I'm here to be efficient and progress towards thwarting bugs/misconceptions. If you have to answer the same thing twice, you should consider writing it down and make it easily accessible, especially for a framework where you expect people to build their own configuration.

As it reads: people who wants fine-grained control over their GUI and have computing tasks are 'targeted' by AwesomeWM. You re-word your statement or reiterate who the project is targeting. I don't see any other proper solution.

There are some things to sort out.

How has this project lived for more than ten years, being as customizable and extensible as it is, but still have documentation as if it was less than a year old? The development of documentation vs. code is extreme and frankly not something I'd personally want to share with the world. AwesomeWM - being an open-source project - should encourage improvements from the community, especially as time goes on and definitions, directions, and paths change.
To be completely honest, I see myself as a modern man using whatever tools to enhance my experience. I use what I see fit (generally things I know what's doing reading source if necessary) and improve whenever I can. When I look at awesomewm and how it's maintained, it seems like the focus is more on 'this is for elite people' 'learn, love, don't share.' and not 'ease of use' and 'this is how you do x'. At this point, there should be a thriving modding community, an effortless way of sharing configurations, and most of all documentation explaining most of the things (+10 years seriously) going on in awesomewm and how to use something. BTW updates should be documented before being added, that's just common sense and one small point of how the docs are 'mistreated'. My way of doing things is generally way more involved than the everyday user, even though awesomewm is some of the hardest documentation I've had to understand... especially for wm framework. For comparison, I had no trouble reading and learning XMonad, but I stopped using it because I couldn't gist the meaning of Haskell and didn't understand the source. It was awesome to write in Haskell though, and I'll return to that whenever I have some math-heavy tasks. My point still stands, awesomewm documentation is lack-luster. What are the reasons for not having better documentation besides having to use ldoc and only writing a minimal amount of actual documentation (reasoning, explanations etc.)?

I have the feeling for people who run just the default configuration and want to make minor tweaks, that's not even the right tool and they'd be better off with something like i3. I always thought this is more a tool if you really want to "build your own window manager", but don't want to mess with C or too deep understanding of several X standards

This is the general outlook of the project, it seems. "Oh, you don't want to spend the hours upon hours learning what we know but don't share in an easily digestible format? Use I3, you pleb." The problem is that DWM is more natural to configure and manage than awesomewm, so the statement doesn't hold up, does it? The actual problem is awesomewm being unnecessarily difficult to learn because of lousy documentation (missing documentation, as there's mostly only references with minimal comments/reasoning).

The (quite sane) default configuration is a monolithic monster you'd have to spend many hours with to understand fully. I'm not saying that this is bad (correctly done modularity has always won though), but what is stopping the website from having a reasonable list of sane setups? One could even argue that a lot of the defaults should be provided with several alternatives and have people create their config (not copy a file as a 'power user'). The problem is that giving someone 'rc.lua' and stating this is the absolute best way we could figure in 10+ years of development, oh btw there's no documentation for x and x updated things,. You have to figure everything out because in the 10+ years of this project, not one person has had the time, passion or ability to describe most of awesome in a digestible way.

AwesomeWM could easily be a default choice wm, as it is a fantastic piece of technology, that - with sane defaults - works on most distributions. If everything was organized and described in a much more professional manner, people could use it without spending hours upon hours trying to understand something that could be easily explained by someone who already understands it. XMonad is not for ordinary people, but the way the documentation was written makes it so anybody can get started (even though Haskell and by extension XMonad is hard to read and work with) I see no reason why awesomewm is lagging so much information about itself besides people not doing it — staying with 'ldoc' that hasn't seen development in several years and arguing that > "A static website using the current framework and no mandatory Javascript are also pretty much hard requirements. We had a website infrastructure at some point (media wiki, flyspray, apache). It did not end well. I don't want to go back there."(link) is not something I resonate with at all.

I've looked through issues and have tried getting an overview of what's happening with awesomewm and where it's going. My findings have been current maintainers/contributors pushing to keep the current state of things and arguing against reason with stuff like 'it has to be x framework & backend did not end well. I don't want to go back there'. The experience I have and from what I've gathered so far is that people involved in this project want it to stay 'underground' or elitist instead of focusing on making it a great project with a definete plan. There's politics and personal reasons involved in a project that has nothing to do with either.

Utter Linux newbies are using AwesomeWM and are posting on places like Reddit. You are interacting with these people, even provide help and try to help them on their way. BUT there's no way that you would ever improve the documentation or re-think which majority of people the project is actually used by and act accordingly. AwesomeWM seems to have already decided something at one point, and whoever suggests otherwise is wrong because of those reasons made years ago.

The interactions mentioned above are incredible to me. How are you content answering the same super newbie questions every day on Reddit (use that without JS please) and not improving or adding documentation to the project as people keep wanting x information?

I still maintain my points stated in the previous comments, especially regarding onboarding new contributors.

I would like to mention that my statement in the op, "The short of the long is that this project seems dead, I want confirmation if you're looking to improve the project or if this will continue as a clearly hobby/side project." was ill-thought through. What I meant was: given the amount of time this project has had to improve every aspect of it, why hasn't more been done?

Lastly, I'm not expecting anyone to do anything. It might come off like that, but I am here just to ask questions and get a clearer understanding of the project as a whole. If things are as I've perceived, and aren't going to change, I'm probably best off forking awesome and trying my luck at starting a community. I'm not expecting any single person here (maintainer or otherwise) to do anything, to quite the contrary point, am I expecting to do most of this myself or alongside others with the same goal of ease-of.use, efficiency and optimization.

we have 2 interesting sayings in russian:

I'm probably best off forking awesome and trying my luck at starting a community. I'm not expecting any single person here

"I was pursuing you for 3 days, just to tell what i don't care about you"

// from "An Ordinary Miracle", 1979

"To talk is not to move the sacks"

// folk-origin

and good luck with GlimpsomeWM ^___^

I guess stereotypes exist for a reason.

Have fun.

awesomeWM / awesome

Documentation #3137