* [Wish List Item 627] User display of Footnote, Bibliography & Short Footnote text

[tatewise]

Background:
Users have requested ways to include formatted Footnote, Bibliography & Short Footnote text in Queries, Reports, Exported GEDCOM files, etc, in threads such as:
footnote, short footnote, and bibliography text (22439)
RM7 -> FH7, lost some citation formatting, other citation questions (21649)
Currently the Footnote, Bibliography & Short Footnote text only appears in the Citation Window side panel and near the end of Reports in the Sources and Bibliography sections.

Problem:
Users cannot include formatted Footnote, Bibliography, or Short Footnote text in a Query Result Set, Records Window Column, Custom Report Item, Diagram Box, or anywhere else that supports expressions.
A custom Plugin cannot offer a comprehensive solution because the only viable function fhSrcEnableAutoTitle(...) does not support citation-specific fields nor font style codes for italics, bold, underscore, etc, that may be used in formatted Footnote, Bibliography & Short Footnote text.

Proposal:
Provide a mechanism, maybe a function, that returns formatted Footnote, Bibliography, or Short Footnote text including font style.

A data reference would identify the context for the formatting and may be a Citation field or a Source record.
However, for Source records, any citation-specific fields in the format would be discarded.
Both generic and templated Source Citations and the :BOOK and :TITLE qualifiers shall be supported.

The returned text would include font styles, probably in rich text format, so when used in Reports or in Plugins the font styles will be faithfully reproduced. Other contexts such as Query Result Sets and Records Window Columns would suppress the rich text styling as happens currently with rich text Notes, etc.

As an example, perhaps the existing GetDisplayText(...) function could gain an optional third parameter that specifies whether Footnote, Bibliography, or Short Footnote text is to be returned and is only valid when the first parameter data item is a Citation field or a Source record.

Benefits:
Users could include Footnote, Bibliography, or Short Footnote text in say a Query Result Set and use Row filters to display subsets.
Users could customise say the Source Summary Report to include formatted Footnote, Bibliography, or Short Footnote text.
Plugin authors could produce Result Sets or GEDCOM files that include formatted Footnote, Bibliography, or Short Footnote text including font styles where possible.

[ColeValleyGirl]

In light of Additional Formatting Options for Bibliography, Footnotes etc. (22453), perhaps modify references to BOOK and TITLE to be more generic?

[tatewise]

I'm not sure how to be more generic. They are what they are. Alternatively, perhaps not mention them at all.

The whole point of this request is that FH performs the same formatting as it does to render the Citation Window side panel but returns the rich text to the user. Whatever current or future features apply to the Citation Window side panel apply to the formatting required to satisfy this request.

[ColeValleyGirl]

I'm not sure how to be more generic. They are what they are. Alternatively, perhaps not mention them at all.

The whole point of this request is that FH performs the same formatting as it does to render the Citation Window side panel but returns the rich text to the user. Whatever current or future features apply to the Citation Window side panel apply to the formatting required to satisfy this request.

I wouldn't mention them.

[Gary_G]

I'd suggest avoiding the "how" of the implementation. Avoiding design constraints is a generally accepted principle in requirements specifications and allows designers to choose the best possible implementation to meet the user needs.

Perhaps all one really needs to say is a slightly polished form of,

"Provide user accessible variables containing the post-processed results for Footnote, Bibliography & Short Footnote, as they currently appear in the Citation Window side panel and near the end of Reports in the Sources and Bibliography sections."

What do you think?

[tatewise]

Gary, I'm not convinced that "user accessible variables" provides enough descriptive detail.
Where would such variables exist bearing in mind that there is a multitude of Footnote, Bibliography & Short Footnote text instances?
FH Expressions cannot access variables in the way that Plugins can. They can only handle one data reference or function returned value at a time.

In this case, I believe some of the how is important considering that the text must be handled by Expressions.

[Gary_G]

Mike;

Perhaps saying "accessible by both users and LUA" might be a solution that would avoid design constraints and address your concern?

[ColeValleyGirl]

Proposal:
Provide a mechanism, maybe a function, that returns as Rich Text the formatted Footnote, Bibliography, or Short Footnote text including font style for a Source or Citation identified by a data reference.

A data reference to a Citation or Source record would identify the context for the formatting and may be a Citation field or a Source record.
However, for Source records, any citation-specific fields in the format would be discarded. (This needs discussion -- footnotes without citation details are nonsense.).
Both generic and templated Source Citations and the :BOOK and :TITLE qualifiers shall be supported. All types of Sources and formatting will be supported.] (Even this might be redundant).

The returned text would include font styles, probably in rich text format, so when used in Reports or in Plugins the font styles will be faithfully reproduced. Other contexts such as Query Result Sets and Records Window Columns would suppress the rich text styling as happens currently with rich text Notes, etc. (redundant if we specify Rich Text).

As an example, perhaps the existing GetDisplayText(...) function could gain an optional third parameter that specifies whether Footnote, Bibliography, or Short Footnote text is to be returned and is only valid when the first parameter data item is a Citation field or a Source record. (implementation detail).

More legibly:

Provide a function that returns as Rich Text the formatted Footnote, Bibliography, or Short Footnote text for a Source or Citation identified by a data reference.

All types of Sources and formatting will be supported.

[ColeValleyGirl]

Mike;

Perhaps saying "accessible by both users and LUA" might be a solution that would avoid design constraints and address your concern?

If we have a function, Lua can access it.

[Gary_G]

Helen;

I'm all for being more succinct. Given Mikes concern, I trust that using "function" would also enable query users to use the data without too much difficulty.

I do have an issue with dropping any reference to the format of the content. I think referring to the citation panel and reports, as an illustration of user-expectations, is key.

[ColeValleyGirl]

I do have an issue with dropping any reference to the format of the content. I think referring to the citation panel and reports, as an illustration of user-expectations, is key.

Isn't specifying Rich text sufficient?

[tatewise]

Are we all happy with my Background, Problem and Benefits sections to be included in the Wish List entry?

I am happy with Helen's suggested Proposal.

That leaves the scenario of Source record data references when the format includes Citation-specific fields.
This probably only impacts 'lumped' Source Citations that typically require Citation-specific fields.
Helen, it seems you don't like the idea of simply disregarding them, so what do you suggest?
Should the function return some kind of error message text instead?
It could substitute some Rich Text to indicate where a Citation-specific field is omitted.

[tatewise]

... I trust that using "function" would also enable query users to use the data without too much difficulty.

Gary, that comment suggests you have not grasped the way functions are applicable to everywhere expressions are allowed in Queries, Reports, Diagrams, Records Window Columns, etc, etc. They are a global feature used throughout FH. May I suggest you review the Advanced Topic help for Expressions and Understanding Data References and Functions?

[ColeValleyGirl]

Are we all happy with my Background, Problem and Benefits sections to be included in the Wish List entry?

I'm happy with them.

That leaves the scenario of Source record data references when the chosen format includes Citation-specific fields.
This probably only impacts 'lumped' Source Citations that typically require Citation-specific fields.
Helen, it seems you don't like the idea of simply disregarding them, so what do you suggest?
Should the function return some kind of error message text instead?
It could substitute some Rich Text to indicate where a Citation-specific field is omitted.

To be honest, I don't know. We might want to talk through some use cases.

[tatewise]

To be honest, I don't know. We might want to talk through some use cases.

The most popular use case is the Templated Source for Essentials - Civil Registration Index which has four Citation-specific fields defined and all are specified in the Footnote and Short Footnote formats.
i.e. Name_Recorded, Date, Registration_District, & Reference
If a Source Record using that template is specified for a Footnote or Short Footnote what text gets returned?

[Gary_G]

I do have an issue with dropping any reference to the format of the content. I think referring to the citation panel and reports, as an illustration of user-expectations, is key.

Isn't specifying Rich text sufficient?

Helen;

As the request is defining user expectations, including a reference to what one exits to see as rich-text would seem to make it more clear. I suppose it's a technicality, but one could provide the rich-text information formatted in a way that doesn't meet the users needs. You have more experience with CP than I. If you feel that they would implicitly understand what we users are trying to achieve, then I'm Ok with your wording.

Could you collect the edits and post a consolidated version, as you have done in past? I really like seeing a thread ending in a "final" version, as you have done in past. It makes it so much easier to identify what will end up in the formal Wishlist.

[Gary_G]

... I trust that using "function" would also enable query users to use the data without too much difficulty.

Gary, that comment suggests you have not grasped the way functions are applicable to everywhere expressions are allowed in Queries, Reports, Diagrams, Records Window Columns, etc, etc. They are a global feature used throughout FH. May I suggest you review the Advanced Topic help for Expressions and Understanding Data References and Functions?

Mike;

From what I've read, I suspected that functions are globally accessible. However; I've learned not to assume that my limited experience with FH internals qualifies me to make that call without confirming the same with more experienced users such as yourself.

[Gary_G]

Now that the general request has crystallized, I too would like to look at some use cases to confirm that it is a solid general solution.
I can see that people come from different points on the Lumper-splitter spectrum and their way of using FH varies greatly.
So; for those who don't normally participate in these discussions, we need to go through this step.

[tatewise]

It does not matter where users exist on the lumper-splitter spectrum. All that matters is whether Citation-specific fields are included in the Footnote or Short Footnote format template. They cannot be used in a Bibliography.

If there are no Citation-specific fields included in the format then it does not matter whether a Citation field or a Source record is specified in the function data reference parameter. The text returned will be identical because only the Source record field values are involved.

If there are Citation-specific fields included in the format then when the data reference is a Citation the text returned by the function will include field values drawn from the Citation-specific fields.
However, if the data reference is a Source record the Citation-specific fields are undefined so what values are returned in the text where those fields are required?
I've suggested they are simply ignored so the returned text would only include all the other formatted text.
Helen seems unsure about that proposal but has not yet offered an alternative.

[ColeValleyGirl]

Helen;

As the request is defining user expectations, including a reference to what one exits to see as rich-text would seem to make it more clear. I suppose it's a technicality, but one could provide the rich-text information formatted in a way that doesn't meet the users needs. You have more experience with CP than I. If you feel that they would implicitly understand what we users are trying to achieve, then I'm Ok with your wording.

Rich Text ought to be sufficient for CP (it's the format in which they store all formatted text). (There are some complications in plugins, but they shouldn't derail this -- unless Mike T says differently). If they provide Rich Text as the output from the function, it can be fed to everything that supports Rich Text.

Could you collect the edits and post a consolidated version, as you have done in past? I really like seeing a thread ending in a "final" version, as you have done in past. It makes it so much easier to identify what will end up in the formal Wishlist.

MIke or I will do that.

[Gary_G]

Mike;

I see what you mean, now. How it is handled could be a potentially contentious issue. I'm looking forward to seeing Helen's views on this.

As for myself; I've been looking at some of my lumper-style projects that I imported from RM and have been silently evaluating how this aspect might affect them. With any new FH projects, I've been trying to restrict lumping (to the extent possible) just to avoid the issue. If the solution makes the situation less of a concern, then I'll be very happy.

[tatewise]

I will post a consolidated proposition for the Wish List when we have resolved the Citation-specific fields issue when a Source record is the context.

[ColeValleyGirl]

It does not matter where users exist on the lumper-splitter spectrum. All that matters is whether Citation-specific fields are included in the Footnote or Short Footnote format template. They cannot be used in a Bibliography.

Although there is a wish list item Allow citation fields in bibliography on sources, I think we can assume that CP will deal with the implications if both Wishes progress.

If there are no Citation-specific fields included in the format then it does not matter whether a Citation field or a Source record is specified in the function data reference parameter. The text returned will be identical because only the Source record field values are involved.

If there are Citation-specific fields included in the format then when the data reference is a Citation the text returned by the function will include field values drawn from the Citation-specific fields.

Agreed.

However, if the data reference is a Source record the Citation-specific fields are undefined so what values are returned in the text where those fields are required?
I've suggested they are simply ignored so the returned text would only include all the other formatted text.
Helen seems unsure about that proposal but has not yet offered an alternative.

Helen knows we have to address this scenario, but doesn't have an answer in her Blue Peter pouch. (Apologies to those of you outside the UK for the reference: Blue Peter was a UK children's TV programme, which often gave demonstrations of how to make something, and then revealed a more polished product with the phrase 'Here's one I made earlier.')

The use cases we should consider will (I think) all focus on querying or reporting on Sources, or writing plugins that analyse Sources. footnote, short footnote, and bibliography text (22439) and Generating a source report including citation from template (22334) are examples.

I think those examples might be best served by returning the Citation-specific field reference (with the appropriate formatting).

Always open to being shot down.

[tatewise]

It is not clear to me how returning the Citation-specific field reference (i.e. the metafield name) would be easily differentiated from an actual Citation-specific field value. How would the user or whoever viewed a derived report know that the text was deficient? (My suggestion of omitting the field suffers from the same problem.)

Maybe an alternative is to return absolutely nothing, i.e. the empty string, to indicate that the Footnote or whatever cannot be formatted because the Citation-specific field values are not available. At least that can be easily detected by software and humans.

BTW: Helen, near the end, you have cited the same example thread twice. I guess that is a typo.

[ColeValleyGirl]

I have amended my post to refer to Generating a source report including citation from template (22334).

It is not clear to me how returning the Citation-specific field reference (i.e. the metafield name) would be easily differentiated from an actual Citation-specific field value. How would the user or whoever viewed a derived report know that the text was deficient? (My suggestion of omitting the field suffers from the same problem.)

Maybe an alternative is to return absolutely nothing, i.e. the empty string, to indicate that the Footnote or whatever cannot be formatted because the Citation-specific field values are not available. At least that can be easily detected by software and humans.

I was thinking it would be returned in {...}