Cleaning up comments and adding to readme

README.md

@@ -1,6 +1,6 @@
 # Gemini Vim Syntax
 
-This repo contains basic syntax highlighting for the [Gemini protocol](https://gemini.circumlunar.space/)'s *text/gemini* format.
+This repo contains basic syntax highlighting for the [Gemini protocol](https://gemini.circumlunar.space/)'s **text/gemini** format.
 
 ## How to install
 
@@ -30,7 +30,15 @@ The current state of the syntax covers all items officially supported by the [ge
 
 I plan to update the syntax when and if the spec adds more items to *text/gemini*.
 
-## Unexpected
+
+## Filetype
+
+This syntax is set up to be used with files labled with the **gmi** extension. For example:
+```
+$ vim my_gemini_map.gmi
+```
+
+## Surprises
 
 It is possible that Windows users may find that the syntax does not work. I do not have a machine to test it on and would love some feedback. If it is not working it likely has to do with line endings. Windows uses \<cairrage-return\><\<line-feed\> and linux/unix use just \<line-feed\>. There are a number of ways to solve this problem ranging from just replacing the newlines manually to using software. In either case it shouldn't be too difficult. 
 

syntax/gmi.vim

@@ -22,9 +22,13 @@ syn match gmiHeader /^#\{1,3}.*$/
 syn match gmiLinkStart /^=>/ nextgroup=gmiLinkUrl skipwhite
 
 " An extremely naive way of handling the URL portion of the link line
-" TODO think about improving this
+" This is left naive in a deliberate attempt to be unambiguous about
+" what part of a link line gemini considers to be the URL, regardless
+" of whether or not it is a valid URL
 syn match gmiLinkUrl /\S\+/ contained nextgroup=gmiLinkTitle skipwhite
 
+" Skipping whitespace from the URL match all text, including whitespace,
+" until the end of the line
 syn match gmiLinkTitle /.*$/ contained
 
 " Handle list items