{"action":"closed","issue":{"url":"https://api.github.com/repos/Swagger2Markup/markup-document-builder/issues/9","repository_url":"https://api.github.com/repos/Swagger2Markup/markup-document-builder","labels_url":"https://api.github.com/repos/Swagger2Markup/markup-document-builder/issues/9/labels{/name}","comments_url":"https://api.github.com/repos/Swagger2Markup/markup-document-builder/issues/9/comments","events_url":"https://api.github.com/repos/Swagger2Markup/markup-document-builder/issues/9/events","html_url":"https://github.com/Swagger2Markup/markup-document-builder/issues/9","id":133023627,"number":9,"title":"Refactor anchor and cross-reference interface and implementation","user":{"login":"Kabhal","id":6772693,"avatar_url":"https://avatars.githubusercontent.com/u/6772693?v=3","gravatar_id":"","url":"https://api.github.com/users/Kabhal","html_url":"https://github.com/Kabhal","followers_url":"https://api.github.com/users/Kabhal/followers","following_url":"https://api.github.com/users/Kabhal/following{/other_user}","gists_url":"https://api.github.com/users/Kabhal/gists{/gist_id}","starred_url":"https://api.github.com/users/Kabhal/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kabhal/subscriptions","organizations_url":"https://api.github.com/users/Kabhal/orgs","repos_url":"https://api.github.com/users/Kabhal/repos","events_url":"https://api.github.com/users/Kabhal/events{/privacy}","received_events_url":"https://api.github.com/users/Kabhal/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2016-02-11T16:40:51Z","updated_at":"2016-02-11T18:40:54Z","closed_at":"2016-02-11T18:40:54Z","body":"Context :\r\n- Many limitations on supported characters in MD and ADOC anchors, and HTML generated ids.\r\n- Partial ADOC support of directly cross-referencing titles (does not work with inter-document cross-references)\r\n- Different normalization rules when cross-referencing titles over custom anchors\r\n- We should always cross-reference a stable id instead of a moving title\r\n\r\nSolution :\r\n- We decide to genericize the anchor/sections/cross-references system in markup-document-builder to a LCD character set for anchors (narrower than the AsciiDoc|Markdown specification).\r\n- No more distinct crossReferenceTitle() : only crossReference and crossReferenceRaw (no filtering, you put what you want in anchor if you know what you do)\r\n- Each section generated with the tool will have an explicit id with anchor = normalized(title)\r\n- All anchors are normalized this way :\r\n\r\n```\r\n- current <- trim()\r\n- current <- Normalizer.normalize(Normalizer.Form.NFD)\r\n- current <- lowercase()\r\n- current <- replaceAll(\"\\\\s+\", ADOC(\"_\") | MD(\"-\") )\r\n- base <- current\r\n- current <- replaceAll(\"[^a-z0-9-_]+\", \"\")\r\nif (current.size() != base.size())\r\n  - current <- hash(original input) // original input to maximize uniqueness\r\nend\r\n\r\nif (ADOC)\r\n  - current <- prefix with \"_\"\r\n  - current <- suffix with \"_\" if endsWith(\"-\") \r\nend\r\n```\r\n\r\n## Anchors rules for documentation purpose\r\n\r\n### Markdown\r\n\r\nSections :\r\n- trim\r\n- supports UTF-8\r\n- only lower cases\r\n- no spaces (replaced with - )\r\n- supported punctuation : [-] ... to be continued\r\n\r\nManual anchors :\r\n- <=> HTML ids\r\n\r\n### AsciiDoc\r\n\r\nSections :\r\n- no limitations\r\n\r\nManual anchors :\r\n- trim\r\n- support upper cases\r\n- no UTF-8\r\n- no space (replaced with _ )\r\n- can't start with a digit\r\n- can't end with '-' ( \\<\\<anchor-\\>\\> : parse error)\r\n- supported punctuation : [:-_.] ... to be continued\r\n- ...\r\n\r\n### HTML\r\n\r\nHTML 4\r\nID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters (UTF-8), digits ([0-9]), hyphens (\"-\"), underscores (\"_\"), colons (\":\"), and periods (\".\").\r\n\r\nHTML 5 : \r\nThe value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.\r\nThere are no other restrictions on what form an ID can take; in particular, IDs can consist of just digits, start with a digit, start with an underscore, consist of just punctuation, etc.\r\nAn element's unique identifier can be used for a variety of purposes, most notably as a way to link to specific parts of a document using fragment identifiers, as a way to target an element when scripting, and as a way to style a specific element from CSS."}}