new-Cite-ext-design.log
dominic.mayers
Actions

Authored By

	dominic.mayers
	Jan 28 2024, 8:33 PM

Size

5 KB

Referenced Files

None

Subscribers

None

new-Cite-ext-design.log
View Options

	commit 1e08bb1897d06c2b9b2a67501f0c1b706bd0e488
	Author: Dominic Mayers <dominic.mayers@meditationstudies.org>
	Date: Sun Jan 28 14:58:22 2024 -0500

	Allow nested refs in references tags

	This commit is offered to inform a discussion about
	nested refs in references tags. It is not to be merged.
	It is known that many wikipedians prefer to put ref tags
	in list within a reference section, not inline in the body
	of the page. It is also known that many pages use nested
	refs (footnotes with their own references). Therefore,
	it is natural to want that these two features can be
	combined. It takes a total new design of the Cite
	extension to achieve that. This commit implements
	the following changes and new strategies.

	1- Simplicity is achieved by leveraging the recursive nature
	of the core parser: the method gardedRef() calls
	recursiveTagParse() to process the content of the ref tags.
	It creates all ref links and ref items (to appear in the
	html) from the ref tags (in the wikitext) that it receives
	from the parser, recursively from itself or from the
	references method. Never any of these need to be
	rolledback ! It stores the ref items in the referenceStack
	and sends the ref links (i.e., the formatted footnoteMarks)
	to the html (via the parser).

	2- The method references() sends the inlist ref tags to
	gardedRef() (indirectly through recursiveTagParse) and
	then formats (by adding backlinks, etc.) the ref items that
	gardedRef() has stored in the referenceStack.

	3- Both, the methods gardedRef() and references(), must
	first process the attributes of the received tag through a
	call to recursiveTagParse() with the second parameter
	$frame, because they might contain template variables.

	4- To distinguish the in list ref tags from the others,
	the Cite class has a property $depthRef that is updated
	by gardedRef() before and after each recursive processing
	of the content of a tag. It also have the property
	$inReferencesGroup that is true when the tag comes
	from a references tag. The inList ref tags are those
	with $inReferencesGroup !== null and $depthRef === 0.

	5- This commit temporarily removes most validation steps,
	because the emphasis is on the logic of the processing
	itself. In that logic, all tags, even those that contain
	errors, are processed. This keeps the logic simple and
	independent of the validation steps. A subsequent commit
	will attach error messages to the erroneous ref items.
	This will make these error messages much easier to
	understand, because they will be close to the erroneous
	items, which will contain backlinks whenever possible.

	6- This commit does not manage the 'follow' attribute that
	is used by some templates as a hack to support some nested
	refs. Managing two approaches to nested refs in the same
	code is error prone. The code after the commit is not
	compatible with templates that manage nested refs using
	the parser function #tag:ref or #tag:references. New
	simple templates have been designed to replace {{Refn}},
	{{Reflist}}, etc. without making any differences for the
	Wikipedia pages and their editors.

	7- The ReferenceStack class have been redesigned. It does
	not have anymore a big pushRef() method to store all aspects
	of a ref item in a single call. Instead, it has a register()
	method to possibly register a new ref item given a ref tag,
	a setHalfParsedHtml() method to set the processed content
	of a registered ref item, a setDir() method to set the
	direction of a registered ref item, etc. The class does
	not include any validation anymore. All validations will be
	done in a class dedicated to validation, but that will be
	done in a subsequent commit.

	8- As for the attributes, calls to recursiveTagParse()
	to process the content of a ref tag or a references tag
	must pass the $frame parameter so that template variables
	are substituted by their value. The methods ref(),
	gardedRef(), references(), etc. have been modified
	accordingly so that the $frame parameter is available.

	9- The content of a tag received by the extension is in
	wikitext and the extension must returns half-parsed html
	(simply html in most cases). The recursiveTagParse()
	method returns half parsed html, which is convenient.
	The methods of the ReferenceMessageLocalizer class are
	designed to process wikitext, which makes sense in most
	cases. This creates a challenge, because the processed
	contents in ref items are in half-parsed html, which cannot
	be mixed with wikitex in message localizers: processing
	this half-parsed html again together with the localized
	wikitex will quote the html. This challenge is addressed
	in the method formatListItem() by replacing the processed
	content by a unique marker before calling the localizer and
	replacing back the marker by the half-parsed content after
	the localized wikitex has been half-parsed.

	10- The commit removes the step for ordering the ref items.
	The ordering of the ref items will be managed separately
	in a subsequent commit.

File Metadata

Mime Type: text/plain
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 14506222
Default Alt Text: new-Cite-ext-design.log (5 KB)

new-Cite-ext-design.logdominic.mayersActions

new-Cite-ext-design.logView Options

File Metadata

Event Timeline

new-Cite-ext-design.log
dominic.mayers
Actions

new-Cite-ext-design.log
View Options