Unit PasDoc_TagManager

See also

TTag.Execute

This will be used to do main work when this @-tag occured in description.

See also

TTag.AllowedInside

This will be checked always when this tag occurs within description.

Values

• toParameterRequired: This means that tag expects parameters. If this is not included in TagOptions then tag should not be given any parameters, i.e. TagParameter passed to TTag.Execute should be ''. We will display a warning if user will try to give some parameters for such tag.
• toRecursiveTags: This means that parameters of this tag will be expanded before passing them to TTag.Execute. This means that we will expand recursive tags inside parameters, that we will ConvertString inside parameters, that we will handle paragraphs inside parameters etc. — all that does TTagManager.Execute.

  If toParameterRequired is not present in TTagOptions then it's not important whether you included toRecursiveTags.

  It's useful for some tags to include toParameterRequired without including toRecursiveTags, e.g. @longcode or @html, that want to get their parameters "verbatim", not processed.

  If toRecursiveTags is not included in tag options: Then everything is allowed within parameter of this tag, but nothing is interpreted. E.g. you can freely use @ char, and even write various @-tags inside @html tag — this doesn't matter, because @-tags will not be interpreted (they will not be even searched !) inside @html tag. In other words, @ character means literally "@" inside @html, nothing more. The only exception are double @@, @( and @): we still treat them specially, to allow escaping the default parenthesis matching rules. Unless toRecursiveTagsManually is present.

• toRecursiveTagsManually: Use this, instead of toRecursiveTags, if the implementation of your tag calls (always!) TagManager.CoreExecute on given TagParameter. This means that your tag is expanded recursively (it handles -tags inside), but you do it manually (instead of allowing toRecursiveTags to do the job). In this case, TagParameter given will be really absolutely unmodified (even the special @@, @( and @) will not be handled), because we know that it will be handled later by special CoreExecute call.

  Never use both flags toRecursiveTags and toRecursiveTagsManually.

• toAllowOtherTagsInsideByDefault: This is meaningful only if toRecursiveTags is included. Then toAllowOtherTagsInsideByDefault determines are other tags allowed by the default implementation of TTag.AllowedInside.
• toAllowNormalTextInside: This is meaningful only if toRecursiveTags is included. Then toAllowNormalTextInside says that normal text is allowed inside parameter of this tag. "Normal text" is anything except other @-tags: normal text, paragraph breaks, various dashes, URLs, and literal @ character (expressed by @@ in descriptions).

  If toAllowNormalTextInside will not be included, then normal text (not enclosed within other @-tags) will not be allowed inside. Only whitespace will be allowed, and it will be ignored anyway (i.e. will not be passed to ConvertString, empty line will not produce any Paragraph etc.). This is useful for tags like @orderedList that should only contain other @item tags inside.

• toFirstWordVerbatim: This is useful for tags like @raises and @param that treat 1st word of their descriptions very specially (where "what exactly is the 1st word" is defined by the ExtractFirstWord function). This tells pasdoc to leave the beginning of tag parameter (the first word and the eventual whitespace before it) as it is in the parameter. Don't search there for @-tags, URLs, -- or other special dashes, don't insert paragraphs, don't try to auto-link it.

  This is meaningful only if toRecursiveTags is included (otherwise the whole tag parameters are always preserved "verbatim").

  TODO: in the future TTagExecuteEvent should just get this "first word" as a separate parameter, separated from TagParameters. Also, this word should not be converted by ConvertString.