Created attachment 366747 [details] [review]
Clarify: ColumnRecords can be static *singletons*

Sharing these between models is highly desirable as it can avoid a lot
of work and waste. So, take the para warning about not making static
ColumnRecords, and reword it to explain why you probably wanted a static
one and what the real solution is.

Created attachment 366748 [details] [review]
Correctly format names: glibmm, Doxygen, &gtkmm;

Wrap remaining occurences of glibmm in <application> tags.
Consistently capitalise non-command references to Doxygen.
Catch one missing opportunity to use &gtkmm;

Created attachment 366749 [details] [review]
Add some missing tags, & swap some for better ones

I hope these are better, at least…

While here, update wording to reflect that gtkmm-4.0 has arrived.

All your patches look fine. Just a few minor comments.

When you mention that gtkmm-4.0 has arrived, you should warn that it's still
highly unstable. Both API and ABI are constantly broken. Don't let people
believe that they can use gtkmm-4.0 in stable applications yet.

Glibmm is mentioned quite frequently. Instead of adding <application> tags
everywhere, it would probably be easier to add

  <!ENTITY glibmm "<application>glibmm</application>">

and write &glibmm;. (At least it had been easier, if it had been done from the
beginning.)

Concerning the master branch: I try to keep the example programs updated when
API is broken in gtk+ 4 and gtkmm 4. Most of the time, the example programs can
be built, but not all of them work well.
The text in index-in.docbook lags behind quite a lot. Probably several chapters
are out of date.

(In reply to Kjell Ahlstedt from comment #4)
> When you mention that gtkmm-4.0 has arrived, you should warn that it's still
> highly unstable. Both API and ABI are constantly broken. Don't let people
> believe that they can use gtkmm-4.0 in stable applications yet.

Good point, will do.


> Glibmm is mentioned quite frequently. Instead of adding <application> tags
> everywhere, it would probably be easier to add
> 
>   <!ENTITY glibmm "<application>glibmm</application>">
> 
> and write &glibmm;

Thanks for the hint. Is the same true for other frequently cited applications/libraries, like for example libsigc++, GTK+, Doxygen?


I've since found a bunch more cases where it seems fairly obvious that <literal> should be swapped for other more precise tags.

I noticed that we seem not to have a tag for signals. Perhaps we could?


I guess a lot of this is practically a moot point if the tags result in the same visual results, though it seems good to make the semantics as accurate as possible.

Another thing I wondered: Should <classname> be used for enums? I wondered that initially but then couldn't find any references to it; usually we use <literal>. However, I just noticed one use for that purpose: <classname>Gtk::SpinType</classname>. So now I'm not sure.

Also, I realised I should omit any changes from typewriter to curly quotes from patches like this - as it'd be suboptimal to introduce inconsistencies by only updating lines that I'm otherwise editing, and impossible to draw the line of where to stop if saying I'll just update nearby quotes. So if we want to do that (I presume yes?) it should be a separate patch that'll hit them all at once.

Comment on attachment 366747 [details] [review]
Clarify: ColumnRecords can be static *singletons*

Attachment 366747 [details] pushed as baeb262 - Clarify: ColumnRecords can be static *singletons*

> I've since found a bunch more cases where it seems fairly obvious that
> <literal> should be swapped for other more precise tags.

I've also seen that <literal> is overused, and often no tag is used where it
should. Feel free to fix such tiny bugs if you like.

> I noticed that we seem not to have a tag for signals. Perhaps we could?

Probably, but it's not obvious which tag to use.

> Should <classname> be used for enums?

I suggest <type>.

(In reply to Kjell Ahlstedt from comment #8)
> > I've since found a bunch more cases where it seems fairly obvious that
> > <literal> should be swapped for other more precise tags.
> 
> I've also seen that <literal> is overused, and often no tag is used where it
> should. Feel free to fix such tiny bugs if you like.

It's hugely overused! I've got a fair sized patch that replaces <literal>s where better tags are available, adds various tags where missing, and updates some capitalisation to match other projects' styles (Doxygen, GDB, etc.).

Correct me if I'm wrong, but I guess it's better just to push that one, since while it may not be perfect, I'm confident that it's definitely an improvement - and it would probably probably more hassle to review in advance than to tweak later as needed.


> > I noticed that we seem not to have a tag for signals. Perhaps we could?
> 
> Probably, but it's not obvious which tag to use.

Once the above patch is pushed, there'll be far fewer other uses of <literal>, so it'll be easier to find places where it's used for signals, at least (as well as code excerpts, macro names, etc.)

 
> > Should <classname> be used for enums?
> 
> I suggest <type>.

Perfect, I hadn't spotted that so didn't realise it existed; thanks. I'll incorporate that into the big patch mentioned above...


What do you think about replacing 'typewriter' quotes and dashes with Unicode equivalents? That seems to be the trend in GNOME documentation generally.

I found a typo in your first patch, the one about singleton ColumnRecords.
s/ininitialized/initialized/


> Is the same true for other frequently cited applications/libraries, like for
> example libsigc++, GTK+, Doxygen?

Yes, you can add more <!ENTITY> definitions if you like.

> Correct me if I'm wrong, but I guess it's better just to push that one.

You're perfectly right.

> What do you think about replacing 'typewriter' quotes and dashes with Unicode
> equivalents? That seems to be the trend in GNOME documentation generally.

I've noticed that it's being done in gtk+ documentation, so gmmproc copies it
into gtkmm. If you want to replace 'typewriter' quotes and dashes in the gtkmm
tutorial, go ahead. Except in code snippets, where
  Glib::ustring hello = "Hello, world!";
shall have the same kind of quotes as in C++ code.

(In reply to Kjell Ahlstedt from comment #10)
> I found a typo in your first patch, the one about singleton ColumnRecords.
> s/ininitialized/initialized/

Thanks, fix pushed.


> > Is the same true for other frequently cited applications/libraries, like for
> > example libsigc++, GTK+, Doxygen?
> 
> Yes, you can add more <!ENTITY> definitions if you like.

I might just add libsigc++ since (all but one, iirc) references to it are already wrapped in <application> tags. The others iirc are usually not.

I guess having tags here is only really useful for lowercase names, to help them stand out against normal sentence text. For names with capitals in them, I'm not sure they gain anything from having tags. What do you think? (I promise I'll try to make this the last opinion I ask for :)


Thanks for the other feedback. I'll go ahead with the Unicode patches. Then I'll find out how badly it all fails to applies to master...

Before I get started on the sure-to-be-arduous master cherry-pick and inevitable million other updates needed, I've pushed a WIP branch with what I've done so far on the gtkmm-3-22 branch:

https://git.gnome.org/browse/gtkmm-documentation/log/?h=wip/dboles/formatting-3

This is just in case anyone is so extremely bored that they feel like reading it, between now and whenever I get a successful rebase/update of this, if they want a preview and might have comments on other things to change. It even builds! ...now

-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtkmm/issues/29.