Class TTagManager

Call OnMessage (if assigned) with given params.

Call DoMessage only if PreExecute is False.

This method is the very essence of this class and this unit. It expands Description, which means that it processes Description (text supplied by user in some comment in parsed unit) into something ready to be included in output documentation. This means that this handles parsing @-tags, inserting paragraph markers, recognizing URLs in Description and correctly translating it, and translating rest of the "normal" text via ConvertString.

If WantFirstSentenceEnd then we will look for '.' char followed by any whitespace in Description. Moreover, this '.' must be outside of any @-tags parameter. Under FirstSentenceEnd we will return the number of beginning characters in the output string that will include correspong '.' character (note that this definition takes into account that ConvertString may translate '.' into something longer). If no such character exists in Description, FirstSentenceEnd will be set to Length(Result), so the whole Description will be treated as it's first sentence.

If WantFirstSentenceEnd, FirstSentenceEnd will not be set.

This is equivalent to Execute(Description, AutoLink, false, Dummy)

This is the underlying version of Execute. Use with caution!

If EnclosingTag = nil then this is understood to be toplevel of description, which means that all tags are allowed inside.

If EnclosingTag <> nil then this is not toplevel.

EnclosingTagData returns collected data for given EnclosingTag. You should init it to EnclosingTag.CreateOccurenceData. It will be passed as EnclosingTagData to each of @-tags found inside Description.

This will be used to print messages from within Execute.

Note that in this unit we essentialy "don't know" that parsed Description string is probably attached to some TPasItem. It's good that we don't know it (because it makes this class more flexible). But it also means that OnMessage that you assign here may want to add to passed AMessage something like + ' (Expanded_TPasItem_Name)', see e.g. TDocGenerator.DoMessageFromExpandDescription. Maybe in the future we will do some descendant of this class, like TTagManagerForPasItem.

This will be inserted on paragraph marker (two consecutive newlines, see wiki page WritingDocumentation) in the text. This should specify how paragraphs are marked in particular output format, e.g. html generator may set this to '<p>'.

Default value is ' ' (one space).

This will be inserted on each whitespace sequence (but not on paragraph break). This is consistent with [https://github.com/pasdoc/pasdoc/wiki/WritingDocumentation] that clearly says that "amount of whitespace does not matter".

Although in some pasdoc output formats amount of whitespace also does not matter (e.g. HTML and LaTeX) but in other (e.g. plain text) it matters, so such space compression is needed. In other output formats (no examples yet) it may need to be expressed by something else than simple space, that's why this property is exposed.

Default value is ' ' (one space).

This will be inserted on @- in description, and on a normal single dash in description that is not a part of en-dash or em-dash. This should produce just a short dash.

Default value is '-'.

You will never get any '-' character to be converted by ConvertString. Convertion of '-' is controlled solely by XxxDash properties of tag manager.

See also

EnDash

This will be inserted on -- in description.

EmDash

This will be inserted on --- in description.

This will be inserted on -- in description. This should produce en-dash (as in LaTeX). Default value is '--'.

This will be inserted on --- in description. This should produce em-dash (as in LaTeX). Default value is '---'.

This will be called from Execute when URL will be found in Description. Note that passed here URL will not be processed by ConvertString.

This tells what to put in result on URL. If this is not assigned, then ConvertString(URL) will be appended to Result in Execute.

This should check does QualifiedIdentifier looks like a name of some existing identifier. If yes, sets AutoLinked to true and sets QualifiedIdentifierReplacement to a link to QualifiedIdentifier (QualifiedIdentifierReplacement should be ready to be put in final documentation, i.e. already in the final output format). By default AutoLinked is false.

When PreExecute is True, tag manager will work a little differently than usual:

• Instead of TTag.Execute, TTag.PreExecute will be called.

• Various warnings will not be reported.

  Assumption is that you will later process the same text with PreExecute set to False to get all the warnings.

• AutoLink will not be used (like it was always false). Also the result of Execute will be pretty much random and meaningless (so you should ignore it). Also this means that the TagParameter for tags with toRecursiveTags should be ignored, because it will be something incorrect. This means that only tags without toRecursiveTags should actually use TagParameter in their OnPreExecute handlers.

  Assumption is that you actually don't care about the result of Execute methods, and you will later process the same text with PreExecute set to False to get the proper output.

  The goal is to make execution with PreExecute set to True as fast as possible.