{"action":"created","issue":{"url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/1469","labels_url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/1469/labels{/name}","comments_url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/1469/comments","events_url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/1469/events","html_url":"https://github.com/asciidoctor/asciidoctor/issues/1469","id":101491821,"number":1469,"title":"support snip-snap in source code including","user":{"login":"skycaptain","id":1119641,"avatar_url":"https://avatars.githubusercontent.com/u/1119641?v=3","gravatar_id":"","url":"https://api.github.com/users/skycaptain","html_url":"https://github.com/skycaptain","followers_url":"https://api.github.com/users/skycaptain/followers","following_url":"https://api.github.com/users/skycaptain/following{/other_user}","gists_url":"https://api.github.com/users/skycaptain/gists{/gist_id}","starred_url":"https://api.github.com/users/skycaptain/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/skycaptain/subscriptions","organizations_url":"https://api.github.com/users/skycaptain/orgs","repos_url":"https://api.github.com/users/skycaptain/repos","events_url":"https://api.github.com/users/skycaptain/events{/privacy}","received_events_url":"https://api.github.com/users/skycaptain/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-08-17T19:21:37Z","updated_at":"2015-08-17T19:40:38Z","closed_at":null,"body":"Asciidoctor provides a mechanism to include source files:\r\n\r\n```asciidoc\r\n[source,ruby]\r\n----\r\ninclude::app.rb[]\r\n----\r\n```\r\n\r\nIt also allows the selection by line numbers:\r\n\r\n```asciidoc\r\n[source,ruby,indent=0]\r\n----\r\ninclude::lib/document.rb[lines=5..10]\r\n----\r\n```\r\n\r\nThis attempt is reasonable, since it does not require the change of the source file. But source code can change rapidly, so do line numbers. Changing everything manually is cumbersome. Therefore, I'm suggesting to implement snip-snap comments. E.g. a Python-file might look like this:\r\n```python\r\ndo_something()\r\n# asciidoctor_snip\r\ndo_something_two()\r\n# asciidoctor_snap\r\ndo_something_three()\r\n```\r\n\r\nAnd the asciidoc might look like:\r\n```asciidoc\r\n[source,python,indent=0]\r\n----\r\ninclude::code.py[snip=0]\r\n----\r\n```\r\nwhere 0 indicates the first snip-snap occurrence. Named snip-snaps might also be allowed:\r\n\r\n```python\r\ndo_something()\r\n# asciidoctor_snip:do_something_two\r\ndo_something_two()\r\n# asciidoctor_snap:do_something_two\r\ndo_something_three()\r\n```\r\n\r\n```asciidoc\r\n[source,python,indent=0]\r\n----\r\ninclude::code.py[snip='do_something_two']\r\n----\r\n```\r\n\r\nEven nested or overlapping snip-snaps might be possible:\r\n\r\n```python\r\ndo_something()\r\n# asciidoctor_snip:do_something_two_three\r\ndo_something_two()\r\n# asciidoctor_snip:do_something_three_four\r\ndo_something_three()\r\n# asciidoctor_snap:do_something_two_three\r\ndo_something_four()\r\n# asciidoctor_snap:do_something_three_four\r\n```\r\n\r\nIf one would not like to annotate the source code with comments, one would be able to add a FILE.ext.snipsnap next to FILE.ext, which translates the corresponding line numbers. The snip-snap comment lines will always be hidden in the output. To be more bullet-proof, one would have to match against the comment literals as well. The most common literals can be found at http://rigaux.org/language-study/syntax-across-languages/Vrs.html#VrsCmmnt\r\n\r\n I'll try to provide a pull-request in the near-future to see if this feature is useful."},"comment":{"url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/comments/131939397","html_url":"https://github.com/asciidoctor/asciidoctor/issues/1469#issuecomment-131939397","issue_url":"https://api.github.com/repos/asciidoctor/asciidoctor/issues/1469","id":131939397,"user":{"login":"robertpanzer","id":1163662,"avatar_url":"https://avatars.githubusercontent.com/u/1163662?v=3","gravatar_id":"","url":"https://api.github.com/users/robertpanzer","html_url":"https://github.com/robertpanzer","followers_url":"https://api.github.com/users/robertpanzer/followers","following_url":"https://api.github.com/users/robertpanzer/following{/other_user}","gists_url":"https://api.github.com/users/robertpanzer/gists{/gist_id}","starred_url":"https://api.github.com/users/robertpanzer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/robertpanzer/subscriptions","organizations_url":"https://api.github.com/users/robertpanzer/orgs","repos_url":"https://api.github.com/users/robertpanzer/repos","events_url":"https://api.github.com/users/robertpanzer/events{/privacy}","received_events_url":"https://api.github.com/users/robertpanzer/received_events","type":"User","site_admin":false},"created_at":"2015-08-17T19:40:38Z","updated_at":"2015-08-17T19:40:38Z","body":"I think what you mean can already be achieved with tags:\r\n\r\n```\r\ninclude::code.py[tags=do_something_one]\r\n```\r\n\r\n```python\r\ndo_something()\r\n#tag:: do_something_one[]\r\ndo_something_else()\r\n#end:: do_something_one[]\r\n```\r\n\r\nThis is also explained in the user manual: http://asciidoctor.org/docs/user-manual/#by-tagged-regions"}}