usingBookmaker.bmh revision a523d2d1554441a79319eb46960d7b5c2dc85d9d 
1#External
2SkXXX
3bmh_SkXXX
4CL
5Go
6Visual_Studio
7##
8
9#Topic Bookmaker
10
11How to use the Bookmaker utility.
12
13Install #A Go # https://golang.org/doc/install ## if needed.  
14Get the fiddle command line interface tool.
15By default this will appear in your home directory.
16
17#Code
18$ go get go.skia.org/infra/fiddle/go/fiddlecli
19##
20
21Build Bookmaker.
22
23#Code
24$ ninja -C out/dir bookmaker
25##
26
27Generate an starter Bookmaker file from an existing include.
28This writes SkXXX.bmh in the current directory, which is
29out/dir/obj/ from an IDE.
30
31#Code
32$ ./out/dir/bookmaker -t -i include/core/SkXXX.h
33##
34
35Copy SkXXX.bmh to docs.
36Use your favorite editor to fill out docs/SkXXX.bmh.
37
38#Subtopic Style
39
40Documentation consists of cross references, descriptions, and examples.
41All structs, classes, enums, their members and methods, functions, and so on,
42require descriptions. Most also require examples.
43
44All methods and functions should include examples if practical.
45
46Descriptions start with an active verb. Descriptions are complete, punctuated
47sentences unless they describe parameters or return values. Parameters and
48returned values are described by phrases that start lower case and do not
49include trailing punctuation.
50
51Descriptions are not self-referential; they do not include the thing they
52describe. Descriptions may contain upper case references to definitions
53but otherwise should be free of jargon.
54
55Descriptions may contain code and formulas, each bracketed by markup.
56
57Similar items may be grouped into topics. Topics may include subtopics.
58
59Each document begins with one or more indices that include the contents of
60that file. A class reference includes an index listing contained topics, 
61a separate listing for constructors, one for methods, and so on.
62
63Class methods contain a description, any parameters, any return value,
64an example, and any cross references.
65
66Each method must contain either one or more examples or markup indicating
67that there is no example.
68
69##
70
71Generate fiddle.json from all examples, including the ones you just wrote.
72Error checking is syntatic: starting keywords are closed, keywords have the
73correct parents.
74If you run Bookmaker inside Visual_Studio, you can click on errors and it
75will take you to the source line in question.
76
77#Code
78$ ./out/dir/bookmaker -e fiddle.json -b docs
79##
80
81Once complete, run fiddlecli to generate the example hashes.
82Errors are contained by the output but aren't reported yet.
83
84#Code
85$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json
86##
87
88Generate bmh_SkXXX.md from SkXXX.bmh and fiddleout.json.
89Error checking includes: undefined references, fiddle compiler errors,
90missing or mismatched printf output.
91Again, you can click on any errors inside Visual_Studio.
92
93#Code
94$ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json
95##
96
97The original include may have changed since you started creating the markdown.
98Check to see if it is up to date.
99This reports if a method no longer exists or its parameters have changed.
100
101#Code
102$ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h
103##
104
105Generate an updated include header.
106This writes the updated SkXXX.h to the current directory.
107
108#Code
109$ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h
110##
111
112#Subtopic Bugs
113
114Bookmaker bugs are tracked #A here # bug.skia.org/6898 ##.
115
116##
117
118#Topic Bookmaker ##
119