Awareness of new or changed features

[Code7R]

Hello,

starting some days or weeks ago, I see a strange frame around drawn on top of the workspace icons. Sometimes it is in the upper left corner of each icon, sometimes in bottom right. I considered bisecting it but cannot reproduce it in Xephyr (see attachment), and I have no quick idea where to start looking.

NOTE: I am having some font issues on this system since a system update about one week ago... this might be related but not sure. "the issues" means strange antialiased look of default fonts and apparently bold fonts in various icewm menus rather than regular font weight.

[bbidulock]

Does it occur on 1.4.2 release?

[gijsbers]

You mean the rectangle on the bottom workspace 4? That could be an iconified window? Did you try turning off PagerShowPreview?

[Code7R]

Yes, it was an iconified window, a hidden instance of Iceowl (pink icon).
And PagerShowPreview turns it off as expected.

Not sure whether I should feel ashamed now, the thing is really confusing.

[gijsbers]

There is also:

#  Draw even minimized windows as unfilled rectangles (if PagerShowPreview=1)
PagerShowMinimized=1

Which allows you to keep the wonderful PagerShowPreview while not being scared by the ghost windows. ;)

[Code7R]

Well, it was surprising for me since I have not turned on the window previews in years or maybe even never.

I think it would be a good idea to have some kind of ReleaseNotes document. Something where users can look for major changes, which would also be the staging area for the release notes for the github tags. What do you think?

NEWS and ChangeLog are not good for this purpose in their current form, most git commit msgs can only be interpreted with the correct context in mind.

[gijsbers]

You have my vote. 👍
My concern is more about having a more frequent releases,
like in RERO.
That would also make it easier to remember what has changed
and summarize that in the announcement.
(BTW, your commits have tabs which mess up the indentation.
Could you perhaps expand tabs into spaces?)

[Code7R]

@bbidulock Would it be acceptable if I change the generation of the NEWS to manual only, and rename it to NEWS.md and start maintaining the contents?

Because that file currently does not fit into the role of a NEWS carrier. It's basically the contents from ChangeLog, reduced and groupped by author name... but real NEWS for users would be something where new things are announced in consistent manner.

Does the end user care about 10 branches being merged here and there? 50 po files regenerated, all listed one by one? Short notes mostly in tech-babble? I don't think so.

[bbidulock]

Sure, I don't have a problem with that. Up until recently changes have been more maintenance and bug fixes, so it didn't matter much. With new features being added, the approach you suggest is better I suppose. Still need to generate a NEWS text file on release that has the release version to satisfy autoconf --gnits (distcheck checks for the release VERSION in the head of the NEWS file).

[bbidulock]

Unfortunately, however, most end users of the window manager do not see the NEWS file at all. It might be more important to update manual pages or html manual instead.

[gijsbers]

Could such a file be maintained in AsciiDoc? Then it could be displayed both on the website and in the Help menu. Maximizing easy access to both existing users (non-developers) and others.

[Code7R]

I considered using MD for now for easier rendering by GH . Can it it display AsciiDoc natively?

Check this up, format proposal:
https://github.com/Code7R/icewm/blob/icewm-1-4-BRANCH/NEWS.md

[gijsbers]

yeah we used to have the latest manpages in asciidoc linked right in the top readme.md just fine. GH knows AD.

[Code7R]

Uhm, I just remembered two reasons why I don't like AD. One being the less natural syntax (for the reader of plain ASCII, compared with MD, and if you go for less readable formats that you can use things like halibut as well). The other being the PRIVACY BREACH by adding web resource references (Google) to all generated files.

[bbidulock]

Yah, and asciidoc generates shitty nroff for man pages too. I think we should convert manual to markdown and manual pages to straight mdoc nroff and drop asciidoc altogether. AD can do tables way better, but I don't see that used extensively anyhoo.

[bbidulock]

Note that you do not have to name it NEWS.md to get GH to render it. Put:

# vim: set ft=markdown:

in the file and GH will recognize it as a markdown file without the .md suffix. Works for asciidoc too:

// vim: set ft=asciidoc:

[bbidulock]

Actually, that is:

[ vim: set ft=markdown: ]: #

which is the only way to do a comment in markdown.

[Vrihub]

Yes please, we need a way to make the casual user aware of new features (and other relevant changes, incompatibilities etc).

The current NEWS and Changelog files are too detailed and developer-oriented; they could be improved by shortening and re-arranging them, but I guess those files are still generated automatically, right?

What about using the release notes published at https://github.com/ice-wm/icewm/releases ?
Assuming they are written manually (as it seems), I'd suggest to split them in two sections:

New features
-----------------
Short description of each new feature and related new configuration directives,
and possibly link to the relevant documentation in man/html/wiki pages

Bug fixes / other changes
---------------------------------
Only list here the major ones (e.g. fixes for long-standing or security-critical bugs),
and just link to NEWS and Changelog files for all the details.

Also, they should be prominently linked from the https://ice-wm.org/ website and from the github project main pages https://github.com/bbidulock/icewm/ and https://github.com/ice-wm/icewm/ (BTW it's not really clear for the casual user why there are two of them). And a copy of them should be in the source archives.

[Vrihub]

What about using the release notes published at https://github.com/ice-wm/icewm/releases ? Assuming they are written manually (as it seems), I'd suggest to split them in two sections:

Have a look at these, for example: https://github.com/mikf/gallery-dl/releases