Page MenuHomePhabricator

Spike: Investigate Named References in VE [8 hours]
Closed, ResolvedPublic

Description

As a Community Tech team member, I want to know to know the various options/considerations for Named References in VE, so that the team can begin planning the work.

Relevant Resources:

Acceptance Criteria:

  • Review the previous wishes from 2019 and 2017 wishlists, as well as relevant Phabricator tasks (see links above)
  • Reach out to Editing team to discuss any potential issues or concerns (note: this is important to do, as there have been some recent changes to citations & VE, from my understanding)
  • Provide an analysis of potential risks associated with this project from a technical perspective
  • Provide an analysis of potential dependencies associated with this project from a technical perspective
  • Provide a recommendation for implementation of this change
  • Provide a rough estimate/sense of difficulty or effort required by this project
  • Investigate the potential of solving this by adding a definition to citation templates in TemplateData that dictates the structure of naming different references based on the type of reference they are (book/journal/etc). This can be done similarly to the way TemplateData maps references to citation templates ('cite book' / 'cite journal' etc) and solve the general concern without having to overcomplicate the VE interface.

Event Timeline

ifried renamed this task from Spike: Named References in VE to Spike: Investigate Named References in VE.Jan 21 2020, 7:53 PM
ifried renamed this task from Spike: Investigate Named References in VE to Spike: Investigate Named References in VE [8 hours].Jan 22 2020, 1:01 AM
ifried moved this task from To Be Estimated/Discussed to Estimated on the Community-Tech board.

Potential risks associated with this project from a technical perspective

  • VE does not have the interface to update existing references that contain the colon name reference (ex :0); therefore, updating current references through VE is not possible at the moment.
  • The work around this wish would only affect new name references. Adding the ability to update existing references would take a significant amount of effort or it may not even be possible. References are moved around and passed around different pages so tracking the different existing use cases can get very complicated.

Potential dependencies associated with this project from a technical perspective

  • The proposed solution would depend on the capabilities of the functionality around TemplateData.

Recommendation for implementation of this change

  • We reviewed this wish with the VE team, and we determined that adding a a parameter in TemplateData to define the structure for the name attribute in references would be the most efficient and quickest way to address this problem.

Rough estimate/sense of difficulty or effort required by this project

  • Based on discussions among Community Tech team, our recommended solution should not be hard to implement, but it would be a matter of learning how we can insert a new parameter in TemplateData that would handle the name reference logic.

Investigate the potential of solving this by adding a definition to citation templates in TemplateData that dictates the structure of naming different references based on the type of reference they are (book/journal/etc). This can be done similarly to the way TemplateData maps references to citation templates ('cite book' / 'cite journal' etc) and solve the general concern without having to overcomplicate the VE interface.

  • Adding a parameter to citation templates in TemplateData that would defined the value for empty name references would be the best solution, and it would also help avoid over complicating the VE interface.
  • The new parameter would be included and the value would be autogenerated and saved through TemplateData when a reference is added using the <ref> tag.
  • We would need to determine the algorithm that would be used to set the unique name reference values. The algorithm can be changed per wiki.
  • As mentioned before, this functionality would not cover existing name references. It would only apply to new added references.

Thank you for the analysis, @HMonroy, this is super helpful!

As you've mentioned, working with citations within VisualEditor is a super complex piece of work, and as @Esanders pointed out to us at great length, citations can be added to a document through multiple mechanisms beyond adding them directly through a single dialog. There are multiple potential templates (dialogs), there's copy/pasting, there's moving references, etc. Adding a UI to these cases will be effectively impossible for us.

We understand the desire to avoid having VisualEditor produce a :0 named reference, so the plan is to mitigate this by changing the way that the names for new named references are generated. We can provide a parameter to TemplateData that is defined per-wiki to tell VisualEditor the structure to generate a more human-readable name for new named references rather than "just" a number.

Following up on @HMonroy's analysis above, here's what we recommend should be the approach and its implications --

  • Add a parameter to TemplateData spec that defines the structure of a named reference based on its type. TemplateData already defines a mapping of citation templates in each wiki; we could add an additional parameter that defines which fields make up a reference name. For example, journal can be defined as [field:journal_name]-[field:volume number]-[auto-increment] while a book can be something like [field:author_last_name]-[field:book-name]-[field:page number]-[auto incremet] etc. VisualEditor can then use this structure with the fields that are filled in automatically by Citoid (or manually by the user) to create a sensible name that is not just a number.
  • Change VisualEditor's automatic name generator from a number, to using this field structure. This would mean changing the code in a single location, would be more confined and easier to manage, and would allow us to provide fallbacks and adjust it in the future if needed.

There are some implications for this:

  • If a citation is "raw" (not using any template) we will have no way of identifying how to create a structured name for it. In those cases, we can fall back on :0 structure.
  • We will still need some numerical auto-increment in the structure in case names that are generated are repeated for different sources.
  • This will require individual wikis to set the structure up in the per-wiki configuration. We could come up with fallbacks to the most common templates, but for wikis who do not set anything up, they may still get the :0 fallback if we have nothing to rely on.

Changing existing names of references is a very complicated operation for VisualEditor that has a lot of vectors for edge cases. Instead, we offer that the above strategy solves 80% of the cases, and if a user encounters a case that is not answered, it is possible to switch to the new wikitext editor that has a very robust interface for "search and replace" and replace those names manually. This can be done for all the cases that the strategy above does not address.

JTannerWMF moved this task from Backlog to External on the Editing-team (Tracking) board.
JTannerWMF added a subscriber: JTannerWMF.

Looks like Ed is providing some guidance here.

Investigation is done; we will await next steps to create followup tickets.

ifried moved this task from Product sign-off to Done on the Community-Tech (Kanban-2019-20-Q4) board.

This spike is complete. We have collected helpful information for the team, which can be used for the next stages of the project. I'm marking this as Done.