diff options
Diffstat (limited to 'doc/user/ref_crea')
| -rw-r--r-- | doc/user/ref_crea | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/doc/user/ref_crea b/doc/user/ref_crea new file mode 100644 index 0000000..994f8d3 --- /dev/null +++ b/doc/user/ref_crea @@ -0,0 +1,139 @@ +@Section + @Title { Creating your own entry types and formats } + @Tag { refstyles } +@Begin +@PP +Although the set of options to the @Code "@Reference" symbol +({@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, etc.) is fixed, you +can add your own reference types and change the formatting of existing types. +@PP +To do this you must be using your own setup file, as explained in +Section {@NumberOf setup}. At the end of the setup file you will find +this line: +reference.print @Index { reference printing style } +ref.style @Index @Code "@RefStyle" +@ID @Code "@SysDatabase @RefStyle { refstyle }" +This tells Lout to consult a database file of reference styles called +{@Code "refstyle.ld"}. These are not references, they are formatting +styles, one for each reference type. The @Code "Sys" in @Code "@SysDatabase" +sys.database @Index @Code "@SysDatabase" +means that this file is stored in the @I { Lout system database directory }, +system.database.dir @Index { system database directory } +refstyle.ld.file @Index { @Code "refstyle.ld" file} +which is where all the standard databases are kept. To change the +formatting of a reference type, or to add your own types, you need to +create your own reference styles database file by copying and modifying +{@Code "refstyle.ld"}. +@PP +To find out the name of the Lout system database directory, type the +Unix command +@ID @Code "lout -V" +Then, supposing that the Lout system database directory is +{@Code "/usr/lout/data"}, type +@ID @Code "cp /usr/lout/data/refstyle.ld mystyle.ld" +to place a copy of the @Code "refstyle.ld" database file in your +mystyle.ld.file @Index { @Code "mystyle.ld" file} +directory, renaming it {@Code "mystyle.ld"}. Since @Code "refstyle.ld" +is read-only, you may also need to change the mode of @Code "mystyle.ld" +to be writable (by @Code "chmod +w mystyle.ld" in Unix). Now replace +@ID @Code "@SysDatabase @RefStyle { refstyle }" +at the end of your setup file by +@ID @Code "@Database @RefStyle { mystyle }" +and Lout will read its reference styles from @Code "mystyle.ld" instead +of {@Code "refstyle.ld"}. Since the two are at +present identical, this has changed nothing so far; but now any changes +you make to @Code "mystyle.ld" will affect your document. Changing +@Code "@SysDatabase" to @Code "@Database" makes Lout search your +current directory for {@Code "mystyle.ld"}, whereas @Code "@SysDatabase" +searches only the system directory. +@PP +In practice you will probably want to store your database of reference +styles in some library directory, so that it can be used by +many documents. A Unix pathname is appropriate for this: +@ID @Code "@Database @RefStyle { \"/usr/jeff/lib/mystyle\" }" +Quotes are needed because of the @Code "/" characters. +@PP +The database entries within @Code "refstyle.ld" and @Code "mystyle.ld" +might look something like this: +@ID @OneRow @Code { +"{ Book @RefStyle @Style" +" { @Reference&&reftag @Open" +" {" +" @Author. @I @Title. @Publisher, @Year." +" }" +" }" +"}" +} +The meaning of the first two lines is beyond our scope, except that +@Code "Book" on the first line means that this is the entry which +defines how references of type @Code Book will be printed. Fortunately, +apart from this one word these two lines are the same in every +reference style entry so you don't need to understand them. The +important part is in the middle: +@ID @Code "@Author. @I @Title. @Publisher, @Year." +The meaning should be clear: first print the author option and a full +stop, then the title option and another full stop in italics, and so +on. To change the formatting of books, change this object. To create +a new reference type, copy the entire database entry, change @Code Book +to a new name of your choice, and change the middle part. Don't forget +to delete the index file @Code "mystyle.li" afterwards, if there is one, +so that Lout knows to generate it afresh. +@PP +Although the entry shown above is perfectly viable, the real entry for +@Code Book is much more complicated, in part because there are more +options than those basic four, but mainly because the real entry goes +to great lengths to do the right thing when options are omitted: +@ID @Tab + vmargin { 0.45vx } + @Fmta { @Col @Code A ! @Col @Code B } +{ +@Rowa A { "{ Book @RefStyle @Style" } +@Rowa A { " { @Reference&&reftag @Open" } +@Rowa A { " {" } +@Rowa A { " { @Author. {}" } B { "} @If @Author" } +@Rowa A { " { @I @Title" } B { "} @If @Title" } +@Rowa A { " { @Word&¬itle" } B { "} @If @Not @Title" } +@Rowa A { " { , @Pinpoint" } B { "} @If @Pinpoint" } +@Rowa A { " { , @Word&&pages @NumSep @Pages" } B { "} @If @Pages" } +@Rowa A { " { , @Word&&page @NumSep @Page" } B { "} @If @Page" } +@Rowa A { " { . @TitleNote" } B { "} @If @TitleNote" } +@Rowa A { " { . @HowPublished" } B { "} @If @HowPublished" } +@Rowa A { " { . @Publisher" } B { "} @If @Publisher" } +@Rowa A { " { . @Organization" } B { "} @If @Organization" } +@Rowa A { " { . @Institution" } B { "} @If @Institution" } +@Rowa A { " { , @Address" } B { "} @If @Address" } +@Rowa A { " { . @Edition" } B { "} @If @Edition" } +@Rowa A { " { , @Month @Year" } B { "} @If @Year @And @Month" } +@Rowa A { " { , @Year " } B { "} @If @Year @And @Not @Month" } +@Rowa A { " { ." } B { "} @If @True" } +@Rowa A { " { {} URL @URL." } B { "} @If @URL" } +@Rowa A { " { {} @Note" } B { "} @If @Note" } +@Rowa A { " }" } +@Rowa A { " }" } +@Rowa A { "}" } +} +The meaning is that each object to the left of an @Code "@If" will be +if. @Index @Code "@If" +printed only if the condition to the right of the @Code "@If" is +true. The condition may contain options, which are considered to be +true if they are not omitted (non-empty), and it may contain {@Code "@And"}, +and. @Index @Code "@And" +or. @Index @Code "@Or" +not. @Index @Code "@Not" +true. @Index @Code "@True" +{@Code "@Or"}, {@Code "@Not"}, and @Code "@True" with the usual precedence +and meaning. Sub-conditions may be enclosed in braces if desired, although +it is best to keep the conditions as simple as possible given the +complexity of the whole setup. +@PP +The objects subject to @Code "@If" are printed with no space preceding +them; any space in the final print will be the result of space within +them, not between them. This is why @Code "@If @True" is not redundant. +@PP +The object @Code "@Word&¬itle" produces @Code "No title" in the +current language; @Code "@Word&&pages" produces {@Code pages} in the +current language, and so on. Consult database @Code "standard.ld" for +standard.ld.file @Index { @Code "standard.ld" file } +other standard words and phrases, and page {@PageOf numsep} for +{@Code "@NumSep"}. +@End @Section |