Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Only support tags at the beginning of a line #4

Open
lpw25 opened this issue Sep 15, 2016 · 2 comments
Open

Only support tags at the beginning of a line #4

lpw25 opened this issue Sep 15, 2016 · 2 comments
Labels
enhancement

Comments

@lpw25
Copy link
Collaborator

lpw25 commented Sep 15, 2016

Whilst I think ocamldoc allows tags to start anywhere in a comment, this is extremely annoying since it means email addresses must be escaped. It also doesn't seem to actually be used anywhere, so we should just get rid of it.
@dbuenzli
Copy link
Contributor

+1. In opkg I even had to escape @ in my html escape function since ocamldoc trips over @ even in an {%html: %} section.

aantron added a commit to ocamllabs/odoc-dev that referenced this issue Jan 4, 2018
@aantron
Handle more word corner cases
f122b0c 
- Words can begin with minus signs, for example negative numbers and
  program options. Minus signs at the beginning of the line that are not
  followed by spaces are therefore treated as part of words (if the next
  character is a word character). Minus signs elsewhere were already
  treated as word tokens. This also allows the janky en- and em-dashes
  "--" and "---" to be parsed as words at the beginning of the line.
- Plus signs are treated the same way for consistency, although they
  have none of the above uses.
- @ characters are now allowed inside words, permitting unescaped email
  addresses. @ characters cannot start words, because this conflicts
  with tag markup. Apart from existing tags, allowing @ at the start of
  words would make it difficult to add new tags later.

Related ocaml-doc/octavius#4.
@aantron
Copy link
Contributor

aantron commented Mar 23, 2018

odoc's parser now still treats @foo in the middle of a line as an attempt to start a tag (and reports an error), but it allows @ to appear inside words, so email addresses don't need escaping. [email protected] parses to:

((output
  (ok
   (((f.ml (1 0) (1 11))
     (paragraph (((f.ml (1 0) (1 11)) (word [email protected]))))))))
 (warnings ()))

I suggest to keep forbidding leading @ in the middle of lines for several reasons:

  • In case we do ever want to support tags in the middle of lines, maybe as some kind of Doxygen-style extension (even though I don't think we would actually want to :)).
  • If we allow leading @, we won't be able to catch a typo in a tag name, if the tag is also mistakenly started in the middle of a line (e.g., see next).
  • Tags do (mistakenly) occur in the middle of lines. While running odoc on opam packages, I found some docstrings like "If something happens, @raise Some_exception". We could still detect this by checking for @raise, etc., specifically, but then we would be creating relatively complex behavior for the user, for probably relatively little gain.

jonludlam pushed a commit to jonludlam/odoc-parser-cleaned that referenced this issue Jul 1, 2021
@aantron
Handle more word corner cases
c9712c0 
- Words can begin with minus signs, for example negative numbers and
  program options. Minus signs at the beginning of the line that are not
  followed by spaces are therefore treated as part of words (if the next
  character is a word character). Minus signs elsewhere were already
  treated as word tokens. This also allows the janky en- and em-dashes
  "--" and "---" to be parsed as words at the beginning of the line.
- Plus signs are treated the same way for consistency, although they
  have none of the above uses.
- @ characters are now allowed inside words, permitting unescaped email
  addresses. @ characters cannot start words, because this conflicts
  with tag markup. Apart from existing tags, allowing @ at the start of
  words would make it difficult to add new tags later.

Related ocaml-doc/octavius#4.
jonludlam pushed a commit to ocaml-doc/odoc-parser that referenced this issue Jul 2, 2021
@aantron
Handle more word corner cases
c0c188f 
- Words can begin with minus signs, for example negative numbers and
  program options. Minus signs at the beginning of the line that are not
  followed by spaces are therefore treated as part of words (if the next
  character is a word character). Minus signs elsewhere were already
  treated as word tokens. This also allows the janky en- and em-dashes
  "--" and "---" to be parsed as words at the beginning of the line.
- Plus signs are treated the same way for consistency, although they
  have none of the above uses.
- @ characters are now allowed inside words, permitting unescaped email
  addresses. @ characters cannot start words, because this conflicts
  with tag markup. Apart from existing tags, allowing @ at the start of
  words would make it difficult to add new tags later.

Related ocaml-doc/octavius#4.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@dbuenzli @lpw25 @aantron