update docs

README.md

@@ -5,8 +5,111 @@
 
 simple HTK & TextGrid handling for go.
 
+## installation
+
+```plaintext
+$ go get github.com/vocatart/golab
+```
+
+## about HTK and TextGrid
+
+[HTK](http://www.seas.ucla.edu/spapl/weichu/htkbook/node113_mn.html) and [TextGrid](https://www.fon.hum.uva.nl/praat/manual/TextGrid_file_formats.html) are two popular formats used for annotating audio, mainly for use in linguistic analysis.
+
+### HTK
+
+while HTK is officially defined as `[start  [end] ] name [score] { auxname [auxscore] } [comment]` golab only 
+supports HTK labels in the format `[start] [end] [name]`. Due to the non-standardization of the HTK format, it is 
+hard to guarantee compatibility. For most linguistic applications, this should be sufficient.
+
+### TextGrid
+
+TextGrid files are internally stored as short format TextGrids. all other information in between the relevant data 
+will be ignored.
+
+#### tiers flag
+
+TextGrid files have a flag that designate whether they contain tiers. For example, a TextGrid that contains tiers 
+would look like the following:
+
+```TextGrid
+   File type = "ooTextFile"
+   Object class = "TextGrid"
+   
+   xmin = 0
+   xmax = 2.3
+   tiers? <exists>
+   size = 3
+   item []:
+       item [1]:
+           class = "IntervalTier"
+           name = "Mary"
+           xmin = 0
+           xmax = 2.3
+           intervals: size = 1
+           intervals [1]:
+               xmin = 0
+               xmax = 2.3
+               text = ""
+       item [2]:
+           class = "IntervalTier"
+           name = "John"
+           xmin = 0
+           xmax = 2.3
+           intervals: size = 1
+           intervals [1]:
+               xmin = 0
+               xmax = 2.3
+               text = ""
+       item [3]:
+           class = "TextTier"
+           name = "bell"
+           xmin = 0
+           xmax = 2.3
+           points: size = 0
+```
+
+while a TextGrid with no tiers would have an `<absent>` tag instead.
+
+```TextGrid
+   File type = "ooTextFile"
+   Object class = "TextGrid"
+   
+   xmin = 0
+   xmax = 2.3
+   tiers? <absent>
+```
+
 ## example
 
-wip
+```go
+package main
+
+import (
+	"github.com/vocatart/golab/htk"
+	"github.com/vocatart/golab/textgrid"
+)
+
+func main() {
+	lab, err := htk.ReadLab("examples/short.lab")
+	if err != nil {
+		panic(err)
+	}
+
+	lab.GetName()        // returns "short"
+	lab.GetAnnotations() // returns []Annotation
+	lab.GetPrecision()   // returns 7 (floating point precision of file, parsed when read in)
+	// etc
+
+	tg, err := textgrid.ReadTextgrid("examples/long.TextGrid")
+	if err != nil {
+		panic(err)
+    }
+
+	tg.GetXmin() // returns 0.0
+	tg.GetXmax() // returns 2.3510204081632655
+	tg.GetTiers() // returns []Tier (can contain IntervalTier or PointTier)
+	tg.GetName() // returns "long"
+}
+```
 
 some .lab examples taken from [kiritan_singing](https://github.com/mmorise/kiritan_singing).

textgrid/textgrid.go

@@ -126,7 +126,7 @@ func (tg *TextGrid) GetSize() int {
 // ReadTextgrid takes a path to a .TextGrid file and reads its contents into a TextGrid.
 func ReadTextgrid(path string) (TextGrid, error) {
 	var tg = TextGrid{}
-	tgDeque := deque.Deque[string]{}
+	tgDeque := new(deque.Deque[string])
 
 	// grab the name element from the path
 	tg.name = filepath.Base(path)
@@ -157,7 +157,7 @@ func ReadTextgrid(path string) (TextGrid, error) {
 	}
 
 	// verify the first two entries in the deque
-	err = verifyHead(&tgDeque)
+	err = verifyHead(tgDeque)
 	if err != nil {
 		return tg, fmt.Errorf("error: textgrid %s has malformed header\n %s", tg.name, err.Error())
 	}
@@ -192,7 +192,7 @@ func ReadTextgrid(path string) (TextGrid, error) {
 		return tg, fmt.Errorf("error: cannot parse textgrid numTiers:\n %s", err.Error())
 	}
 
-	tiers, err := parseTiers(globalXmin, globalXmax, &tgDeque, numTiers)
+	tiers, err := parseTiers(globalXmin, globalXmax, tgDeque, numTiers)
 	if err != nil {
 		return tg, fmt.Errorf("error: cannot parse textgrid tiers:\n %s", err.Error())
 	}