Add (i) info button to date editor with calendar and syntax help#2377
Add (i) info button to date editor with calendar and syntax help#2377dsblank wants to merge 9 commits into
Conversation
Adds a small information button next to the Calendar dropdown in the EditDate dialog. Clicking it opens a popover with a two-column table listing every date type (modifier/quality/calendar combination) with a live example rendered by the current locale's date displayer. This makes it easy for users entering dates in non-English locales to discover the exact syntax their locale expects without consulting external documentation.
- Add Calendar and Dual-dated sections to the (i) info popover so users learn why the calendar selector may be disabled and how slash-year notation works, before the per-locale syntax table. - Move the info button to the upper-left of the Calendar row (left of the "Calendar:" label) for a natural, in-context placement. - Fix Date.set() skipping the round-trip sanity check for empty dates, which caused a spurious DateError on dialog open and left the calendar selector disabled until the user toggled Dual-dated. - Fix show_on_calendar() to bail early for empty dates, preventing a GTK Calendar day-selected signal on uninitialised date values. - Fix GTK translation detection in grampsgui.py to search XDG_DATA_DIRS and /usr/share/locale-langpack so Ubuntu's language-pack-gnome-* packages are found when running from a virtualenv. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
dsblank
changed the title
The local variable 'value' was assigned an 8-tuple for range/span dates and a 4-tuple otherwise; mypy inferred the type from the first assignment and rejected the second. Add an explicit union type annotation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
A leftover placeholder child element in the main vbox was creating an extra empty row at the bottom of the Edit Date dialog. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
I feel that it is unwise to add Help as (paragraph or page sized) chunks of of text as hard-coded strings in Python modules. It seems like such text should be external files in a format that non-programmers can easily change. And that the Weblate system is better suited to individual words, phrases or sentences; not paragraphs or pages. Can the Info system be converted to a re-usable module that can be pointed at a JSON, XML, .htm HTML, .md markdown or .txt text file. So that an Info GUI item can be added elsewhere in Gramps too. |
They are not hardcoded.
It will be filled-in by Weblate. I took a survey and people voted to translate larger sections of text: 
|
|
In Weblate, smaller strings are generally easier to handle. Read the translator comments on the string containing command line examples for example. The string length in this PR seems OK to me though. |
I do not understand this response. “They are not hardcoded” does not seem accurate in the literal sense. If text is embedded in a Python module, it is hard-coded, even when marked translatable. The following part of the module has the ext in your screen capture above. (But the table of examples
Sending Paragraphs/Documents to Weblate is a misinterpretation of the response. (Regardless of interpretation, 5 respondents in a survey is too small to be statistically significant in any direction) As 1 of the 4 respondents supporting "Entire Document", my intent was that the translation should be based on externalized reference document... which provides context and conversational flow... not in translatation-marked words, phrases or sentences. And words, phrases or sentences are the only situation where Weblate should be used to translate. An externalized file would be more translator friendly. Also, full-fledged Help Utility would not be use-friendly in the style of a super-sized roll-over (or click activated) tooltip anchored to a ℹ️ or I've been working a different approach. When a features exceeds the purposes that can be satisfied by tooltips, the developer can link a Help, ℹ️ (or any of the other many Info/help/Faq icons in the Adwaita and Gnome themes). Clicking that will pop a Window that is fed from the README.md (or other designated) file for its content... where GUI icons, hotlinks, bitmap illustration URLs, and text styling can augment the content. (Not limited to Headers, HorzRules, tables and such. It allows 'Help' content to be decoupled from the coding yet leverages the GitHub standard README.md that Developers are already writing. |
That's not a bad idea. But it doesn't exist. We do have a mechanism that does exist (Weblate) and @Nick-Hall believes that these strings are not too long. Feel free to propose or wish-design a different mechanism (but it still has to be translated... how will translators find it and translate it?) |
It is fully functional ... tested as an addon in 5.2, 6.0, and 6.1 version. I have just been holding it back because I was duplicating the same Markdown code in 5 of my addons already. So I spun it out into a bespoke MarkdownUtils (with most GitHub Flavored Markdown plus a bunch of Gramps flavor markdown) module. I'm not even CLOSE to being a software architect. So it needs some input (probably re-design) on where the MarkdownUtils.py could live in the Core. And the MarkdownDash plug living in the core would open a host of possibilities. (Like replacing the "Welcome" gramplet, FAQ gramplet with more attractive variants.) 
|
I'd be glad to work with you on this, but this is independent from this PR. Of course once it exists, we can switch to it. (But we still have to figure out how to get it translated!) |
It currently uses a system where it will use the target filename to feed the content. But if the same filename exists in the I am not confident that this is the best place for the system. |
I would love (absolutely LOVE) your help to make this useful to the whole community. It is certain that I have been going down the Garden path with a few ideas. And that the code is suffering from organic sprawl. Most importantly, if the use becomes as widespread as I expect, it needs to be made as efficient as possible. |
|
I will (cringe) post the proof-of-concept source to my public 6.1addon repository and start the Ideas discussion. For the last week, I've been wrestling with the PluginMgrPlus addon ... which has will have the most pervasive use of the MarkdownUtils. It uses it for the content panels, the interactive help panel and the pop-up Help buttons windows. My thought was that getting all that working smoothly might save some revising of the MarkdownUtils. So far, no tweaks have been necessary. |
Add get_help_topics() to ManagedWindow as an overridable method returning a list of topic dicts (each with a title and either a body string or an examples list). EditDate overrides it with the calendar, dual-dating, and syntax-example sections. The popover callback becomes a generic renderer with no content knowledge, enabling future reuse for search and doc generation across all editor dialogs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add gramps.gen.utils.markdown with a pure-Python tokenizer (parse.py) and gramps.gui.widgets.markdown_render with a GTK3 TextBuffer renderer (render_md, setup_tags). The renderer supports bold, italic, inline code, headings, images (gramps:icon: and gramps:image: URI schemes), and gramps: scheme links for opening editors, navigating records, and switching views. Update EditDate.get_help_topics() to use markdown in body strings (calendar names in **bold**, date syntax examples in `code` spans) and switch cb_show_date_syntax() to render body sections via Gtk.TextView instead of Gtk.Label. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
I refactored the info-text:
Some formatting really helps readability: 
|
…method. get_help_topics() on ManagedWindow and EditDate are now classmethods so help content can be indexed across all editor classes without instantiating any windows. _build_date_examples() becomes a staticmethod since it uses only the global displayer, not instance state. Callers using self.get_help_topics() continue to work unchanged. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The help topic body strings use Markdown formatting (**bold** and `code`). Adding a Translators comment ensures that when strings are extracted into gramps.pot, translators see a note to preserve the Markdown markup. A # fmt: off block is used to keep the string on the same line as _(), which is required for xgettext to associate the comment with the string. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3 participants
Summary
(i)information button to the upper-left of the Calendar row in the Edit Date dialog.1735/6, alternate New Year codes)DateErrorfromDate.set()running a round-trip sanity check on an empty(0,0,0,False)date value). (made a separate PR)show_on_calendar()to bail early for empty dates, preventing a spurious GTK Calendarday-selectedsignal. (made a separate PR)grampsgui.pyto searchXDG_DATA_DIRSand/usr/share/locale-langpack, solanguage-pack-gnome-*packages installed on Ubuntu are found when running from a virtualenv or conda environment. (made a separate PR)Motivation
The motivation for this PR is two-fold:
In English:
In French (the text has not been translated yet):
I hope to add additional ℹ️ buttons with short helpful advice in various places in Gramps.
Test plan
(i)button and confirm the popover shows Calendar, Dual-dated, and syntax sections.language-pack-gnome-eninstalled, confirm no "GTK translations missing" warning on startup.🤖 Generated with Claude Code