# Notebook Database File #-------------------------------------------------- # #--- page #--- {The "#---" [directive] draws a horizontal line across the page. For example, #--- The line above was drawn by a "#---" directive. The "#" character must be in the first column of text. Any text that follows "#---" on the same line is ignored.} 1114045789 #-------------------------------------------------- # #data page #data {The "#data" [directive] indicates that the following lines contain some kind of textual data. The data continues until the matching "[#undata]" directive is encountered, or until the end of the page. By using "#data" and "[#undata]" together you can include multiple blocks of data of various kinds on a single page, interspersed with normal [Notebook Markup]. The syntax of the #data directive is as follows: #data ?type? ?name? ?args...? As always, the "#" must be in the first column of the line. For the moment, text bracketed by #data and #undata is displayed preformatted. In the future, Notebook might have the capacity to format and display specific data types--e.g., other Wiki notations, diagrams, and so forth--in appropriate ways. At that time, different supported types can adjust themselves according to their args. At present, the only specific type recognized and specially handled by Notebook is "html". When [exporting a page to HTML], any text bracketed by "#data html" and "#undata" will be copied to the output unchanged--for example, "<" and ">" will not be translated to "&lt;" and "&gt;".} 1112494473 #-------------------------------------------------- # #meta page #meta {The "#meta" [directive] is used to specify page-specific settings for page formatting and export options. The syntax is as follows: : #meta name value For example, the follow directive indicates that the background color for normal text should be blue -- or at least it would if Notebook paid any attention to it. #meta textbg blue The "#meta" directive is still experimental; and for now is probably best ignored.} 1114045863 #-------------------------------------------------- # #pre page #pre {The "#pre" [directive] tells Notebook to display the following lines as [preformatted text], regardless of what it looks like--but remember that [embedded macro]s are still expanded. The block of preformatted text continues until the next "#unpre" directive, or the end of the page. The "#" in "#pre" and "#unpre" must be in the first column of the line. Note that the the "#pre" and "#unpre" directives themselves are never displayed.} 1111979546 #-------------------------------------------------- # #rem page #rem {The "#rem" directive is used to add undisplayed comments (remarks) to Notebook pages. All text on the "#rem" line is ignored. For example, #pre #rem These are comments; I'll see them when I'm editing, #rem but not when I'm browsing. #unpre An excellent use for the #rem directive is to add search keywords to pages.} 1114958769 #-------------------------------------------------- # #Tcl page #Tcl {The "#Tcl" [directive] indicates that the following lines contain program code in [the Tcl language]. The Tcl code continues until the next "[#unTcl]" directive is encountered, or until the end of the page. By using "#Tcl" and "[#unTcl]" together you can include multiple blocks of Tcl code on a single page, interspersed with normal [Notebook Markup]. Notebook's on-line help is stored in Notebook format; see its [User Code] page for an example of how to use intermingled #Tcl blocks and [Notebook Markup] to good effect. Tcl code is displayed preformatted, and may be executed and loaded into memory on demand; see [Defining new commands]. Consequently, "#Tcl" and "[#unTcl]" are most often used on [User Code Page]s. The "#Tcl" and "[#unTcl]" directive lines are also displayed preformatted.} 1114958883 #-------------------------------------------------- # #undata page #undata {The "#undata" [directive] ends a block of data text. See the "[#data]" page for more information.} 1111979433 #-------------------------------------------------- # #unpre page #unpre {The "#unpre" [directive] ends a block of [preformatted text] that began with "[#pre]". See the "[#pre]" page for more information.} 1098501857 #-------------------------------------------------- # #unTcl page #unTcl {The "#unTcl" [directive] ends a block of Tcl code on a [User Code] page. See the "[#Tcl]" page for more information.} 1098544667 #-------------------------------------------------- # About Notebook page {About Notebook} {Notebook [@version@] -- A searchable, customizeable personal notebook and hypertext system. The Notebook home page is the [Notebook Wiki], at : http://notebook.wjduquette.com Come and visit for news, downloads, updates, etc. Please read the [License]. Copyright (C) 2002, 2003, 2004, 2005 by William H. Duquette -- will@wjduquette.com} 1114297219 #-------------------------------------------------- # about-notebook page about-notebook {#rem command #rem action = Syntax = about-notebook = Description = Loads the "About Notebook" page into the [help browser]. This is equivalent to selecting Help/About Notebook from the application menu. = Examples = about-notebook = Implementation = [@showproc about-notebook@]} 1115583968 #-------------------------------------------------- # Advanced Features page {Advanced Features} {The following topics describe how to get the most use of Notebook through by extending it to meet your needs. Most of these features involve using one or more [Notebook Commands]. * [Magic Button]s * [Embedded Macro]s * [Customizing the User Menu] * [Customizing the Edit Menu] * [Defining New Commands] * [The Tcl Language]} 1111725533 #-------------------------------------------------- # askfor page askfor {#rem command = Syntax = askfor prompt = Description = Writes the prompt to the status line, and then lets the user enter a response. When the user presses Enter, the response is returned. If the user cancels the input by pressing Escape, the entire command will be cancelled. See also [request], which is [askfor] on steroids. = Examples = The following command asks for your name, and [insert]s it into the editor. You could add it to your [editmenu]. #Tcl proc insert-name {} { insert [askfor "Your name"] } #unTcl = Implementation = [@showproc [current]@]} 1114961175 #-------------------------------------------------- # assert page assert {#rem command = Syntax = [@signature assert@] = Description = The [assert] command defines an "assertion": a logical statement that must be true if you've not made any coding errors. If the statement is not true, then [assert] throws an error and you can see a full stack trace in the [Message Log] A judicious use of [assert] can make it much easier to debug your code. See also [require]. = Examples = Suppose you've added some procs to your [User Code] page. One of the procs defines a helper command that should only be called by your other procs: #pre proc DoSomethingToAPage {name} { ... } #unpre As you've designed your code, it's a programming error to call DoSomethingToAPage for a page that doesn't exist. You can indicate this clearly by using an assertion: #pre proc DoSomethingToAPage {name} { assert {[pageexists $name]} . . . } #unpre = Implementation = [@showproc assert@]} 1114961188 #-------------------------------------------------- # back-page page back-page {#rem command #rem action = Syntax = back-page = Description = This command can be invoked as a [User Interface Action]. While browsing pages, displays the previously-browsed page. Calling this command is equivalent to pressing the "back" button. = Examples = Inserted into a page, the following [magic button] will take you back to whichever page you'd been looking at previously: #pre [%Go Back!|back-page%] #unpre = Implementation = [@showproc back-page@]} 1115584008 #-------------------------------------------------- # Basic Features page {Basic Features} {The following topics will help you gain a basic understanding of how Notebook works and what it can do for you. * [Getting started with Notebook] * [Finding your way around] * [Editing an existing page] * [Creating links to other pages] * [Creating new pages] * [Notebook Markup] * [Inline Images] * [Link Bars] * [Exporting Notebook Pages] * [Exporting Entire Notebook Files] * [Creating a Daily Log] * [International Character Sets]} 1114361665 #-------------------------------------------------- # Bulleted Paragraph page {Bulleted Paragraph} {One common use of Notebook is to create lists of things. To create a bulleted list, just put a "*" at the beginning of each entry (the * has to be in the first column of the line). * First bullet * Second bullet * Third bullet. Note that a bullet item can be very short, or it can be an an entire paragraph. If the text is so long that it has to wrap to a second or third line, or even longer, all of the lines will be indented properly under the first line. You can even create outlines--lists with multiple levels of indentation--just by entering as many "*" characters as you want indents. If your page contains this, for example, * First level ** Second level *** Third level **** Fourth level then it displays like this: * First level ** Second level *** Third level **** Fourth level You can indent up to nine levels.} 1027183868 #-------------------------------------------------- # cancel-edits page cancel-edits {#rem command #rem action = Syntax = cancel-edits = Description = While editing a page, cancels your edits and returns to browsing. If you've made any changes you'll be asked to confirm that you want to abandon them. This is equivalent to pressing the "X" button on the [page editor]'s toolbar, or the Escape key. = Examples = cancel-edits = Implementation = [@showproc cancel-edits@]} 1115584033 #-------------------------------------------------- # clipboard page clipboard {#rem command = Syntax = clipboard ... = Description = clipboard is a built-in Tcl/Tk command for accessing the system clipboard; see the official Tcl/Tk documentation for specifics. = Examples = Here are some simple uses of the clipboard command. To clear the clipboard: #pre clipboard clear #unpre To copy a text string to the clipboard: #pre clipboard clear clipboard append "My string" #unpre To retrieve the contents of the clipboard: #pre set text [clipboard get] #unpre = Implementation = [@showproc clipboard@]} 1114961237 #-------------------------------------------------- # close-window page close-window {#rem command #rem action = Syntax = close-window = Description = Closes the current window; if the current window is the last one, exits the application altogether. This is equivalent to selecting File/Close Window. = Examples = close-window = Implementation = [@showproc close-window@]} 1115584057 #-------------------------------------------------- # codeget page codeget {#rem command = Syntax = codeget ''name'' = Description = Retrieves and returns all Tcl code from the named page, that is, all text between #Tcl and #unTcl [directives]. If the page does not exist, or contains no Tcl code, codeget returns the empty string. Warning: this command expands and parses the named page. Calling it from an [embedded macro] for the particular page in which the macro is embedded might cause Notebook to hang. = Examples = #pre set usercode [codeget "User Code"] #unpre = Implementation = [@showproc codeget@]} 1115584079 #-------------------------------------------------- # Color Preferences page {Color Preferences} {Notebook uses many different text colors, each with its own specific purpose. On the Colors tab of the User Preferences dialog box you can select the foreground and background colors you prefer for each purpose: = Page Browser Colors = These settings are used by the [page browser]. * Normal Text: Normal text. * Title Text: Page titles. * Preformatted Text: Blocks of preformatted text or data. * Tcl Code: Blocks of Tcl code. * Link Text: Links to other pages. * Button Text: [Magic button] text. * Warning Text: Badly formatted [magic button]s, and [embedded macro]s that could not be expanded. * Search Text: Text that matches the text in the [search box]. = Page Editor Colors = This setting is used by the [page editor]. * Editor Text: All text in the [page editor].} 1114223956 #-------------------------------------------------- # copy-page-as page copy-page-as {#rem command #rem action = Syntax = copy-page-as ''format'' ?''name''? = Description = Copies the named page to the clipboard in the specified format; Notebook prompts the user for the page name if no name is given. The format can be any of the export formats supported by Notebook; see [exportformat] for a complete list. This command can be invoked as any of the following [User Interface Action]s: * [copy-page-as-html-page] * [copy-page-as-html-text] * [copy-page-as-plain-text] * [copy-page-as-expanded-markup] * [copy-page-as-raw-markup] * [copy-page-as-mediawiki] See also [formatas], [exportformat], [copy-this-page-as], [export-page-as], and [export-this-page-as]. = Examples = copy-page-as html-text "Recent Changes" = Implementation = [@showproc copy-page-as@]} 1115584105 #-------------------------------------------------- # copy-page-as-expanded-markup page copy-page-as-expanded-markup {#rem action = Description = This action prompts for the name of a page, then copies the page's text to the clipboard. The copied text is simply the page's raw markup, with all macros expanded. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961691 #-------------------------------------------------- # copy-page-as-html-page page copy-page-as-html-page {#rem action = Description = This action prompts for the name of a page, then translates the page's text to HTML, formatted as a complete HTML page. The HTML is copied to the clipboard. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961698 #-------------------------------------------------- # copy-page-as-html-text page copy-page-as-html-text {#rem action = Description = This action prompts for the name of a page, then translates the page's text to HTML body text, suitable for pasting into an HTML document. The HTML is copied to the clipboard. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961701 #-------------------------------------------------- # copy-page-as-mediawiki page copy-page-as-mediawiki {#rem action = Description = This action prompts for the name of a page, then translates the page's text to [MediaWiki] markup, suitable for pasting into a [MediaWiki] page. The markup text is copied to the clipboard. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961705 #-------------------------------------------------- # copy-page-as-plain-text page copy-page-as-plain-text {#rem action = Description = This action prompts for the name of a page and then copies the page's text to the clipboard, first formatting it nicely as plain text; the result is suitable for pasting into an e-mail message. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961707 #-------------------------------------------------- # copy-page-as-raw-markup page copy-page-as-raw-markup {#rem action = Description = This action prompts for the name of a page and then copies the page's raw markup to the clipboard, just as though you'd edited the page, selected all of the text in the editor, and copied it manually. This action has no precisely equivalent [Notebook command]; instead, use the [copy-page-as] command.} 1114961711 #-------------------------------------------------- # copy-string page copy-string {#rem command #rem action = Syntax = copy-string = Description = This command can be invoked as a [User Interface Action]. While you're editing or browsing a page, [copy-string] copies the selected text to the clipboard. [copy-string] is most useful as an item on your [editmenu]. = Examples = Placed in your [User Code Page], the following code will define an editor context menu with one item: #pre editmenu { Copy {copy-string} } #unpre = Implementation = [@showproc copy-string@]} 1115584129 #-------------------------------------------------- # copy-this-page-as page copy-this-page-as {#rem command #rem action = Syntax = copy-this-page-as ''format'' = Description = Copies the current page to the clipboard in the specified format, which can be any of the export formats supported by Notebook; see [exportformat] for a complete list. This command can be invoked as any of the following [User Interface Action]s: * [copy-this-page-as-html-page] * [copy-this-page-as-html-text] * [copy-this-page-as-plain-text] * [copy-this-page-as-expanded-markup] * [copy-this-page-as-raw-markup] * [copy-this-page-as-mediawiki] See also [formatas], [exportformat], [copy-page-as], [export-page-as], and [export-this-page-as]. = Examples = #pre copy-this-page-as html-text #unpre = Implementation = [@showproc copy-this-page-as@]} 1115584146 #-------------------------------------------------- # copy-this-page-as-expanded-markup page copy-this-page-as-expanded-markup {#rem action = Description = This action copies the current page's text to the clipboard. The copied text is simply the page's raw markup, with all macros expanded. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961720 #-------------------------------------------------- # copy-this-page-as-html-page page copy-this-page-as-html-page {#rem action = Description = This action translates the current page's text to HTML, formatted as a complete HTML page. The HTML is copied to the clipboard. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961724 #-------------------------------------------------- # copy-this-page-as-html-text page copy-this-page-as-html-text {#rem action = Description = This action translates the current page's text to HTML body text, suitable for pasting into an HTML document. The HTML is copied to the clipboard. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961728 #-------------------------------------------------- # copy-this-page-as-mediawiki page copy-this-page-as-mediawiki {#rem action = Description = This action translates the current page's text to [MediaWiki] markup, suitable for pasting into a [MediaWiki] page. The markup text is copied to the clipboard. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961731 #-------------------------------------------------- # copy-this-page-as-plain-text page copy-this-page-as-plain-text {#rem action = Description = This action copies the current page's text to the clipboard, first formatting it nicely as plain text; the result is suitable for pasting into an e-mail message. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961734 #-------------------------------------------------- # copy-this-page-as-raw-markup page copy-this-page-as-raw-markup {#rem action = Description = This action copies the current page's raw markup to the clipboard, just as though you'd edited the page, selected all of the text in the editor, and copied it manually. This action has no precisely equivalent [Notebook command]; instead, use [copy-this-page-as].} 1114961737 #-------------------------------------------------- # Creating a Daily Log page {Creating a Daily Log} {I find that one of the best ways I have of keeping organized and on top of what I'm doing is to keep a daily log. On the top of the page I keep my "to do" list; the remainder of the page consists of my log entries, listed by day in reverse chronological order. Before I wrote Notebook, I kept my log using a normal text editor and one long text file; this was convenient in some ways, but very unwieldy in others, particularly when it came time to trim the file and move the older log entries into archival storage. Fortunately, Notebook automates the whole process for me. It automatically stores the entries for a specific day in a page of their own for ease of searching and editing, but also makes a "main log" page that displays my "to do" list (and anything else I'd like), the most recent seven entries in the log, and then an index list of all of the old entries. More than that, I can have separate logs on as many subjects as I like. = Creating a new log page = * Decide what you'd like your main log page to be called. Mine is called "To Do". * Put a link to the page on your Home page, and click on it to create the page. See [Creating links to other pages] and [Creating new pages]. * Put whatever text you'd like at the top of the page: your to do list, a list of projects, or whatever you'd like--or nothing. * At the bottom of the page, type in this: #pre [@lb@]logpage[@rb@] #unpre * [logpage] is an [embedded macro] that turns the page into a log page. It does all of the heavily lifting for you. * Save the page. When it displays, you'll see the words "Edit Today's Entry" at the bottom of the page. * To edit today's entry, click on "Edit Today's Entry". Notebook will automatically create a new page for the day's entry, and take you to the editor. The first line of the new page will look something like this: #pre [@lb@]logentry "To Do" 2002-07-20[@rb@] #unpre * Leave this line at the top of the page! [logentry] is an [embedded macro] that makes the page part of your daily log. * Add whatever you'd like to the bottom of the page, and save it. * You'll be taken back to your main log page--and now, your first entry will be there. Note that it automatically begins with today's date. = Using your log page = To browse your log, or add new entries, just go to your main log page. * To edit the text at the top of the page, edit the page as you would any other page. * To edit today's entry, or to create an entry for today, just click on "Edit Today's Entry". * To edit a previous entry, click on the word "edit" on the same line as its date. To view a previous entry as a separate page, click on the word "view" on that same line. * If I'm editing the current day's entry frequently, I'll often click on the word "view" to view the entry page, and then just edit it as a normal page. That's all there is to it!} 1114142245 #-------------------------------------------------- # Creating links to other pages page {Creating links to other pages} {Notebook's most prominent feature is the ability to link pages together. You've been using this feature quite a bit as you read through this on-line help material. To create a link from one page to another page, edit the first page and type the other page's name in square brackets where ever you'd like the link to be. For example, to create a link to your Home page you'd type this: #pre [Home] #unpre When you save the page, you'll see that you've created a link. Click on it, and it will take you to the page you chose. Links are normally shown in blue text. Sometimes you want to link to a page, but you want to use something other than the page's name as the link text. For example, to link to your Home page as "My Home Page", you'd type this: #pre [My Home Page|Home] #unpre Everything before the vertical bar character ("|") is displayed; everything after is the page name to which you want to link. Note that you can't put a link in [preformatted text], because that's always displayed exactly just the way you typed it, including the brackets.} 1114141522 #-------------------------------------------------- # Creating New Pages page {Creating New Pages} {You can create a new page in several ways. The most useful way to create a new page is simply to enter a link to it on some existing page. Your Home page is often a good choice; some people like to create a New Pages page for this purpose. The best place for the link is on some page related to your new page. See [Creating links to other pages] for how to create a link. A link to a nonexistent page looks [like this]. Not only do the the bracket characters appear, but they are colored differently than the rest of the link. This is a reminder to you that the page doesn't exist. To actually create the page, just click on the link. Notebook will ask if you want to create it. Type "y" into the status line, and press the return key, and Notebook will open the editor for the new page. See [Editing an existing page] for more on editing pages, and [Notebook Markup] for how to make you page look the way you want it to. Alternatively, you can select the Page/Edit Page... menu item, and Notebook will ask you for the name of the page to edit. Type it into the status line and press return, and Notebook will open the editor for the new page.} 1072222873 #-------------------------------------------------- # current page current {#rem command = Syntax = current ?''num''? = Description = By default, returns the name of the page you're currently browsing or editing. The command has some significant additional behavior when used in an [embedded macro], based on the value of the num argument; you'll only care about this if you have pages that expand and include the text of other pages. level : current returns the number of pages in the expansion stack. n : If n is a number less than &lb;current level&rb;, returns the name of the nth page in the expansion stack, counting from the top of the stack. Note that &lb;current 0&rb; is thus the name of the page that contains the [embedded macro] that called current. #n : If n is a number less than &lb;current level&rb;, returns the name of the nth page in the expansion stack, counting from the bottom of the stack. Note that &lb;current #0&rb; is thus the name of the topmost page that is being expanded, i.e., the page being expanded so that it can be parsed and displayed in the [page browser]. = Examples = The [logpage] command derives the name of [logentry] pages from the name of the [current] page. On a [logentry] page, &lb;current&rb; will return the page's name when it's displayed in the [page browser], but the [logpage]'s name when the [logentry] is displayed as part of the [logpage]. On the other hand, &lb;current 0&rb; will return the [logentry] page's name regardless of how the [logentry] page is displayed. = Implementation = [@showproc current@]} 1115584165 #-------------------------------------------------- # Customizing the Edit Menu page {Customizing the Edit Menu} {The Edit Menu is a user-defined menu that pops up when you right-click or control-click in the [page editor]. It allows you to invoke [Notebook Commands] or other commands you've written yourself from any page in your notebook. To customize the Edit Menu, use the [editmenu] command on your [User Code Page]. See also [Defining new commands].} 1072805067 #-------------------------------------------------- # Customizing the User Menu page {Customizing the User Menu} {The User Menu is a user-defined menu that pops up when you right-click or control-click in the [page browser]. It allows you to invoke [Notebook Commands] or other commands you've written yourself from any page in your notebook. To customize the User Menu, use the [usermenu] command on your [User Code Page]. See also [Defining new commands].} 1072804521 #-------------------------------------------------- # cut-string page cut-string {#rem command #rem action = Syntax = cut-string = Description = This command can be invoked as a [User Interface Action]. Whenever you're editing text, [cut-string] will cut the selected text onto the clipboard just like the Edit/Cut menu item does. [cut-string] is most useful as an item on your [editmenu]. = Examples = Placed in your [User Code Page], the following code will define an editor context menu with one item: #pre editmenu { Cut {cut-string} } #unpre = Implementation = [@showproc cut-string@]} 1115584188 #-------------------------------------------------- # cycle-recent-pages page cycle-recent-pages {#rem command #rem action = Syntax = cycle-recent-pages = Description = While browsing, invoking this action repeatedly will cause the browser to cycle through the last ten or so pages you've looked at during the current session. This action is equivalent to selecting Page/Cycle Through Recent Pages. = Examples = cycle-recent-pages = Implementation = [@showproc cycle-recent-pages@]} 1115584205 #-------------------------------------------------- # Daily Log page {Daily Log} {A Daily Log is a dated log or diary, managed by Notebook for efficient editing and searching. See [Creating a Daily Log] for more information.} 1029001645 #-------------------------------------------------- # dbfile page dbfile {#rem command = Syntax = [@signature dbfile@] = Description = [dbfile] returns the absolute path name of the current notebook file. = Examples = [dbfile] can be useful if you want to pass the notebook file to some external program. For example, on a Unix system the following magic button would do a CVS commit of your notebook file: #pre [%Commit|exec cvs commit -m"Backup" [dbfile]%] #unpre = Implementation = [@showproc dbfile@]} 1114961904 #-------------------------------------------------- # dbsave page dbsave {#rem command = Syntax = [@signature dbsave@] = Description = Saves the contents of the current notebook to disk. The notebook is saved automatically whenever you edit, rename, or delete a page; however, if you write code that directly manipulates the contents of your notebook it might not get saved immediately. The documentation for each [notebook command] that affects the content of your notebook will indicate whether the command saves the notebook or not. In general, high-level commands like [newpage], [rename-page] and [delete-page] save the notebook; low-level commands like [pageset], [pagedelete] and [pagerename] do not. = Examples = The following magic button will remove all text from the current page (including the button itself) and save the notebook. #pre [%Clear This Page%|pageset [current] "" ; dbsave%] #unpre = Implementation = [@showproc dbsave@]} 1114961907 #-------------------------------------------------- # Defining new commands page {Defining new commands} {= Introduction = Part of Notebook's power is that you can extend it to suit yourself by defining new commands in [the Tcl language]. If you're a diehard Tcl programmer, then or course you could do this by getting the Notebook source and modifying it as you chose; but even a normal user can extend Notebook without touching the original source code. Be warned, though: extending Notebook is a kind of programming, and you have to be ready to deal with the consequences of mistakes in your code. If you're new to Tcl programming, you might want to experiment in a separate notebook that doesn't contain your important data, and copy your successes over as you perfect them. = The User Code Page = Every notebook contains a page called "User Code" that exists to contain your own custom [Notebook commands]. You can display "User Code" in any of the normal ways, or you can select the Magic / User Code menu item. The "User Code" page always contains at least one line, that looks like this: [#Tcl] -- Enter new commands below You can put any kind of text you like at the top of the page, ahead of the "[#Tcl]" line; you can put your own Tcl code after it. The magic of the "User Code" page is that the Tcl code on it is automatically loaded whenever you open the notebook, so the commands you define there are automatically available on all of your other pages. To add new code, just edit the "User Code" page. When you're done, save it; you can reload it by selecting the Magic / Load User Code menu item. Then try your new commands in [magic button]s and [embedded macro]s. = Adding Additional Code Pages = You don't need to put all of your Tcl code in the "User Code" page. If there's something you're working on that you don't want loaded automatically at start up, put it on its own page, preceded by a [#Tcl] directive. You can load the code once you've written it using the Magic / Load Current Page menu item. Once you've debugged your new code, you can copy it to your "User Code" page; or, alternatively, you can leave it where it is and put a [load-page] command on the [User Code] page to load it at start up. The [load-page] command should follow the [#Tcl] directive on the [User Code] page. For example, #pre #Tcl load-page "User Code: More Code" #unpre If the new code page will execute commands defined on your [User Code] page ''as it loads'', then the [load-page] command should follow those command definitions. If all your new code page does is define new commands or call existing [Notebook Commands], then the [load-page] command can go anywhere on the page. = Your First New Command = An [embedded macro] is really just a Tcl command that returns some text; the text replaces the macro when the page is displayed. Here's a simple macro that returns the day and time. You can copy it into your "User Code" page just as you see it here. #pre proc dayAndTime {} { set now [clock seconds] return [clock format $now -format "%A, %I:%M:%S %p"] } #unpre Unfortunately, any lengthy discussion of [the Tcl language] is beyond the scope of this help document. = Debugging Your Code = As soon as you start programming, you'll find that you need to debug your code. Notebook offers you two tools: the [Message Log] window and the [msg] command. The [Message Log] is a scrolling log of all messages written to the status line at the bottom of the Notebook Window, with the newest messages at the top. [msg] is a [Notebook Command] that adds messages to the log. If you're trying to figure out what's going on in your code, it's often useful to sprinkle it with calls to [msg].} 1115589667 #-------------------------------------------------- # delete-page page delete-page {#rem command #rem action = Syntax = delete-page ?''name''? = Description = This command can be invoked as a [User Interface Action]. Deletes a page from your notebook, and saves the notebook. If name is given, [delete-page] deletes and the named page and returns immediately; otherwise, [delete-page] prompts the user to enter a page name, and then asks them to confirm that the page should be deleted. If you wish to delete many pages at one time, use delete-pages instead. = Examples = Pressing the following [magic button] would cause the current page to be deleted. #pre [%Delete Me|delete-page [current]%] #unpre This one, on the other hand, will prompt the user for a page to delete. #pre [%Delete Something|delete-page%] #unpre = Implementation = [@showproc delete-page@]} 1116795614 #-------------------------------------------------- # delete-pages page delete-pages {#rem command #rem action = Syntax = delete-pages ?pages? = Description = This command can be invoked as a [User Interface Action]. Deletes a list of pages from your notebook, and saves the notebook. If no list of page names is given, delete-pages will delete the pages whose names are selected in the [Index Sidebar]. Either way, the user is asked to confirm whether the specified pages should be deleted or not. = Examples = The following bit of code would delete all pages whose names include the word "Cheese". #pre delete-pages [pages *Cheese*] #unpre = Implementation = [@showproc delete-pages@]} 1116795556 #-------------------------------------------------- # Deprecated Actions page {Deprecated Actions} {The following [User Interface Actions] are deprecated in Notebook [@version@]. That means that they still work, but might be removed in a later version; therefore they shouldn't be used in new code. The documentation for each has the name of the new action that replaces the deprecated action. [@linktable { goto-index goto-recent-changes }@]} 1114959419 #-------------------------------------------------- # Deprecated Notebook Commands page {Deprecated Notebook Commands} {The following [Notebook Commands] are deprecated in Notebook [@version@]. That means that they still work, but might be removed in a later version; therefore they shouldn't be used in new code. The documentation for each has the name of the new command that replaces the deprecated command. [@linktable { goto-index goto-recent-changes }@]} 1115516538 #-------------------------------------------------- # Directive page Directive {A special kind of [Notebook markup] command. See [Directives].} 1027188510 #-------------------------------------------------- # Directives page Directives {A directive is a special command to Notebook about the current page. Every directive begins with a "#" character in the first column on a line. The remainder of the line is the directive proper. At present, Notebook understands the following directives: * [#---] * [#rem] comment text * [#meta] name value * [#pre] ... [#unpre] * [#Tcl] ... [#unTcl] * [#data] type ?name? ?args? ... [#undata] Most directives affect the way the page is displayed; by default, though, the directives themselves are not. Directive display can be enabled on the [Miscellaneous preferences] tab of the [User Preferences] window. If Notebook does not recognize a directive (e.g., #NotADirective it will displayed as preformatted text.} 1114216925 #-------------------------------------------------- # Edit Menu page {Edit Menu} {The Edit menu has the following items; the related [User Interface Action] is listed after each in parentheses. * Edit / Undo ([undo-change])
Undoes the last editing change. * Edit / Redo ([redo-change])
Undoes the last undo. * Edit / Cut ([cut-string])
Cuts the selected text to the clipboard. * Edit / Copy ([copy-string])
Copies the selected text to the clipboard. * Edit / Copy Page / As HTML Text ([copy-this-page-as-html-text|copy-this-page-as])
Formats the current page as HTML body text, suitable for pasting into an existing HTML page, and copies the formatted text to the clipboard. See [Exporting a Page to HTML] for more information. * Edit / Copy Page / As an HTML Page ([copy-this-page-as-html-page|copy-this-page-as])
Formats the current page as a complete HTML page and copies the formatted text to the clipboard. See [Exporting a Page to HTML] for more information. * Edit / Copy Page / As Plain Text ([copy-this-page-as-plain-text|copy-this-page-as])
Formats the current page as plain text, suitable for pasting into an e-mail message or text file, and copies the formatted text to the clipboard. * Edit / Copy Page / As Expanded Markup ([copy-this-page-as-expanded-markup|copy-this-page-as])
Expands any [embedded macro]s in the current page and copies the resulting Notebook markup text to the clipboard. * Edit / Copy Page / As Raw Markup ([copy-this-page-as-raw-markup|copy-this-page-as])
Copies the raw markup of the current page to the clipboard. This is equivalent to highlighting a page's text in the [Page Editor] and using * Edit / Copy. * Edit / Paste ([paste-string])
Pastes text from the clipboard into the editor. * Edit / Insert Page... ([insert-page])
While editing, prompts the user for a page name, and inserts the raw text of that page into the editor at the insertion point. * Edit / Find String... ([find-string])
Moves the cursor to the [Search Box] so that you can enter a search string. The any occurrences of the search text will be highlighted in the [page browser] or [page editor] (whichever is open). If the [page editor] is open, then pressing Return in the Search Box will take you back to the editor and move the insertion cursor to the next occurrence of the search text. * Edit / Find Again ([find-again])
After a successful search in the [Page Editor], this item finds the next occurrence of the string. If selected repeatedly, it will eventually wrap around to the beginning of the page. * Edit / Replace ([replace-string])
While editing, prompts the user for two strings and replaces all occurrences of the first string that follow the insertion point in the current page with the second string.} 1116796416 #-------------------------------------------------- # edit-page page edit-page {#rem command #rem action = Syntax = edit-page ?''name''? ?''nextpage''? ?''template''? = Description = This command can be invoked as a [User Interface Action]. While browsing a notebook, this command will load a page into the editor. If the name argument is given, it specifies the name of the page to edit; otherwise, Notebook will prompt the user for the page name. nextpage names the page to view when done editing; it defaults to the edited page. If template is given, it is a text string that will be inserted into the page. Note that the named page need not yet exist; if it doesn't, it will be created automatically when the user saves his or her edits. = Examples = See the implementations of [edittodayslog] and [logentry]. = Implementation = [@showproc edit-page@]} 1115584263 #-------------------------------------------------- # edit-preferences page edit-preferences {#rem command #rem action = Syntax = edit-preferences = Description = Pops up the [User Preferences] dialog box. This is equivalent to selecting File/Preferences. = Examples = #pre edit-preferences #unpre = Implementation = [@showproc edit-preferences@]} 1115584277 #-------------------------------------------------- # edit-this-page page edit-this-page {#rem command #rem action = Syntax = edit-this-page = Description = This command can be invoked as a [User Interface Action]. While browsing, loads the current page into the editor. Calling this command is equivalent to selecting Page/Edit This Page from the application menu. = Examples = You might conceivably add "edit-this-page" to your [usermenu]. = Implementation = [@showproc edit-this-page@]} 1115584294 #-------------------------------------------------- # Editing an existing page page {Editing an existing page} {You can edit a page in several ways: * Navigate to the page, and press the "Edit" button on the toolbar; this button shows a pencil over a piece of paper. * Click on a link to an undefined page. * Select the Page/Edit Page... menu item, and type in the name of the page you'd like to edit. * Press Ctrl+`, and enter [edit-page] on the command-line; press Enter, and then type in the name of the page you'd like to edit. Once you're editing a page, you can use the normal editing keys for your platform. When you're done editing, type Ctrl+S, or press the "Checkmark" button on the toolbar. See [Page Editor] for more on using the editor. Note that Notebook doesn't display the text you enter quite the way you type it. Instead, it makes it easy to create links and other special things. See [Notebook Markup] for information on how Notebook displays what you type.} 1114967688 #-------------------------------------------------- # editmenu page editmenu {#rem command = Syntax = [@signature editmenu@] = Description = Defines the editor context menu. You can access the items on this menu by right-clicking in the [page editor]. The menuitems argument is a list of item labels and [notebook commands]--clicking on the label will execute the associated command. If the item label is the single word "separator", then a separator will be added to the menu instead of a normal item. [editmenu] returns the current list of items. = Examples = If you included the default set of pages in your notebook when you created it (the set that includes the "Tour"), then your [editmenu] was initially defined like this: #pre editmenu { Undo undo-change Redo redo-change separator {} Cut cut-string Copy copy-string Paste paste-string "Insert Page..." insert-page } #unpre Suppose you have a page called "My Template" that contains boilerplate you like to include in a number of pages. The following code adds an item to insert it: #pre editmenu { Undo undo-change Redo redo-change separator {} Cut cut-string Copy copy-string Paste paste-string "Insert Page..." insert-page "Insert My Template" {insert-page "My Template"} } #unpre = Implementation = [@showproc editmenu@]} 1114961912 #-------------------------------------------------- # Editor Preferences page {Editor Preferences} {This tab allows you to set parameters that affect the behavior of Notebook's page editor. Tab Width: Pressing the Tab key inserts space characters until the next tab stop is reached. By default, tab stops are every four spaces; you can choose any tab width you like. AutoWrap: Notebook doesn't wrap text as you insert and delete letters, like a word processor; rather, it respects the carriage returns you enter, and preserves them just as you enter them. If AutoWrap is enabled, however, pressing the space bar or the return key near the end of the line will cause that line to be wrapped to the next line. Wrap Column: The "wrap column" is used when AutoWrap is enabled; it determines approximately how long individual lines should be. It defaults to 74 characters. AutoIndent: It's often desirable to indent a line to match its predecessor. If both AutoWrap and AutoIndent are enabled, then wrapped lines are automatically indented to match the previous line. In addition, if AutoIndent is enabled then pressing Tab at the very beginning of the line indents to match the previous line.} 1114224376 #-------------------------------------------------- # edittodayslog page edittodayslog {#rem command #rem action = Syntax = [@signature edittodayslog@] = Description = This is the [notebook command] executed by the "Edit Today's Entry" [magic button] on a [daily log] page. In general, there's little reason to call this command directly, unless you wanted to have several "Edit Today's Entry" button on a [daily log] page. = Examples = See the implementation of [logpage]. = Implementation = [@showproc edittodayslog@]} 1114961398 #-------------------------------------------------- # Embedded Macro page {Embedded Macro} {An embedded macro is a special command you insert into a page in special brackets, #pre [@lb@]Like this[@rb@] #unpre When the page is displayed, the macro gets replaced with something else. If you were to go to the Index page and edit it, for example, you'd see this: #pre [@lb@]pageIndex[@rb@] #unpre [pageIndex] is a [Notebook Command] that produces an index of the pages in your Notebook. You can use it in your own pages, too. For example, suppose you'd created a bunch of pages about a kitchen remodel that you were planning. You could put an index of all of them on your main Kitchen Remodel page by including the macro #pre [@lb@]pageIndex *Kitchen* [@rb@] #unpre --- assuming that all of the page names included the word "Kitchen". Notebook has a number of [Notebook Command]s you can use as embedded macros, and you can define your own commands as well. The typical use for a macro is to format up some dynamic text for display in your page. In this case, the macro should return text that follows the [Notebook Markup]. You can also write macros that take some special action whenever you view the page. Be aware, macros are expanded before any formatting is done; consequently, macros will be expanded even if they appear in [preformatted text]. = If you have problems... = It's quite possible to write an embedded macro that makes a page unviewable, or that might even hang up the Notebook application altogether. Consider the following: #pre [@lb@]while 1 {msg "Oh, No!"}[@rb@] #unpre If you go to a page that contains this macro, Notebook will hang as the macro writes "Oh, No!" to the status line infinitely many times. Should you encounter this kind of problem, here's what you can do: * Kill the Notebook application as best you can. * Restart Notebook and open the notebook file. * Select the Page/Edit Page... menu item, and type in the name of the page containing the problem macro. * Edit or delete the problem macro, and save the page. This should handle most problems--unless, of course, the problem macro is on your Home page. In that case, you need to disable embedded macros altogether: * Restart Notebook without specifying a notebook file. * Uncheck "Expand Macros?" on the Magic menu. * Open the notebook file. * Edit the problem page as described above. * Once you're sure it's OK, check "Expand Macros?" on the Magic menu again.} 1114222918 #-------------------------------------------------- # Explicit Line Break page {Explicit Line Break} {Normally, Notebook treats a set of consecutive lines beginning with normal text as a paragraph, which is wrapped for attractive display. Consider the following input, in which each line is clearly meant to be separate: #pre Title: Badgers Author: Brock Marshworthy #unpre Here's what it ends up looking like: Title: Badgers Author: Brock Marshworthy To fix this, you can insert an explicit line-break with the <br> tag: #pre Title: Badgers
Author: Brock Marshworthy #unpre This breaks the line without breaking the paragraph: Title: Badgers
Author: Brock Marshworthy The &lb;br&rb; tag also works within bulleted and indented paragraphs: #pre * Title: Badgers
Author: Brock Marshworthy #unpre The second line is properly indented. * Title: Badgers
Author: Brock Marshworthy If you want to begin a new, unindented paragraph at a point where Notebook would not ordinarily break paragraphs, you can put a "-" (optionally followed by some whitespace) as the first character on the line: #pre * This is a bulleted paragraph. This is a continuation of the bulleted paragraph. * This is a bulleted paragraph. - This is an unindented paragraph #unpre As you can see, "-" at the beginning of the line forces a new paragraph to start, just as "*" and ":" do. * This is a bulleted paragraph. This is a continuation of the bulleted paragraph. * This is a bulleted paragraph. - This is an unindented paragraph} 1115516942 #-------------------------------------------------- # export-notebook-as-html-file page export-notebook-as-html-file {#rem action = Description = This action saves the entire contents of a Notebook file to a single HTML file, with links between the different Notebook pages. The first page is always the "Home" page; after that, pages are in alphabetical order. Between each pair of pages is a navigation bar with links to the "Home" and "Index" pages. See [Exporting a Page to HTML] for more information. This action has no equivalent [Notebook command].} 1114961744 #-------------------------------------------------- # export-notebook-as-html-set page export-notebook-as-html-set {#rem action = Description = This action exports each page in a Notebook file to HTML, one HTML file per page, with links between the different pages. The user is prompted for a directory in which to create the HTML files; if the directory isn't empty, the user will be told so and asked whether or not to export the Notebook. Each page will begin and end with a navigation bar, with links to the "Home" page, the "Index" page, and the next and previous pages in alphabetical order by page name. The page file names are based on the page names, as follows: * ".html" is added on the end. * The name is converted to lower case, e.g., "Home" becomes "home.html". * All whitespace in the page's name is replaced with underscores, e.g., "Recent Changes" becomes "recent_changes.html". * If there's a conflict between two names, an extra underscore and number are added to one of them. For example, suppose your Notebook contained pages called "This And That" and "This_And_That". From Notebook's point of view these are two different names, but following the above rules yields the same string, "this_and_that.html". One of them will become something like "this_and_that_1.html". See [Exporting a Notebook to HTML] for more information. This action has no equivalent [Notebook command].} 1114961748 #-------------------------------------------------- # export-page-as page export-page-as {#rem command #rem action = Syntax = export-page-as ''format'' ?''name''? = Description = Saves the named page to disk in the specified format; Notebook prompts the user for the page name if no name is given, and also for the file name. The format can be any of the export formats supported by Notebook; see [exportformat] for a complete list. This command can be invoked as any of the following [User Interface Action]s: * [export-page-as-html-page] * [export-page-as-html-text] * [export-page-as-plain-text] * [export-page-as-expanded-markup] * [export-page-as-raw-markup] * [export-page-as-mediawiki] See also [formatas], [exportformat], [copy-page-as], [copy-this-page-as], and [export-this-page-as]. = Examples = #pre export-page-as html-text "Recent Changes" #unpre = Implementation = [@showproc export-page-as@]} 1115584340 #-------------------------------------------------- # export-page-as-expanded-markup page export-page-as-expanded-markup {#rem action = Description = This action saves the contents of a Notebook page to a text file. The user is prompted for both the page name and the file name. The saved text is simply the page's raw markup with all macros expanded. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961752 #-------------------------------------------------- # export-page-as-html-page page export-page-as-html-page {#rem action = Description = This action saves the contents of a Notebook page to a text file, first translating the page to HTML. The user is prompted for both the page name and the file name. The saved text is formatted as a complete HTML page. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961755 #-------------------------------------------------- # export-page-as-html-text page export-page-as-html-text {#rem action = Description = This action saves the contents of a Notebook page to a text file, first translating the page to HTML. The user is prompted for both the page name and the file name. The saved text is formatted as HTML body text, suitable for inclusion in a larger HTML document. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961758 #-------------------------------------------------- # export-page-as-mediawiki page export-page-as-mediawiki {#rem action = Description = This action saves the contents of a Notebook page to a text file, first translating the page to [MediaWiki] markup. The user is prompted for both the page name and the file name. The saved text is suitable for pasting into a [MediaWiki] page. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961761 #-------------------------------------------------- # export-page-as-plain-text page export-page-as-plain-text {#rem action = Description = This action saves the contents of a Notebook page to a text file, first formatting it nicely as plain text. The user is prompted for both the page name and the file name. The saved text is suitable for pasting into an e-mail message. See [Exporting Notebook Pages] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961764 #-------------------------------------------------- # export-page-as-raw-markup page export-page-as-raw-markup {#rem action = Description = This action saves the contents of a Notebook page to a text file. The user is prompted for both the page name and the file name. The saved text is precisely what you'd see if you edited the page in the [Page Editor]. This action has no precisely equivalent [Notebook command]; instead, use the [export-page-as] command.} 1114961767 #-------------------------------------------------- # export-this-page-as page export-this-page-as {#rem command #rem action = Syntax = export-this-page-as ''format'' = Description = Saves the current page to disk in the specified format; Notebook prompts the user for the page name if no name is given. The format can be any of the export formats supported by Notebook; see [exportformat] for a complete list. This command can be invoked as any of the following [User Interface Action]s: * [export-this-page-as-html-page] * [export-this-page-as-html-text] * [export-this-page-as-plain-text] * [export-this-page-as-expanded-markup] * [export-this-page-as-raw-markup] * [export-this-page-as-mediawiki] See also [formatas], [exportformat], [copy-page-as], [copy-this-page-as], and [export-page-as]. = Examples = #pre export-this-page-as html-text #unpre = Implementation = [@showproc export-this-page-as@]} 1115584357 #-------------------------------------------------- # export-this-page-as-expanded-markup page export-this-page-as-expanded-markup {#rem action = Description = This action saves the contents of the current Notebook page to a text file. The user is prompted for the file name. The saved text is simply the page's raw markup with all macros expanded. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961779 #-------------------------------------------------- # export-this-page-as-html-page page export-this-page-as-html-page {#rem action = Description = This action saves the contents of the current Notebook page to a text file, first translating the page to HTML. The user is prompted for the file name. The saved text is formatted as a complete HTML page. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961783 #-------------------------------------------------- # export-this-page-as-html-text page export-this-page-as-html-text {#rem action = Description = This action saves the contents of the current Notebook page to a text file, first translating the page to HTML. The user is prompted for the file name. The saved text is formatted as HTML body text, suitable for inclusion in a larger HTML document. See [Exporting a Page to HTML] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961786 #-------------------------------------------------- # export-this-page-as-mediawiki page export-this-page-as-mediawiki {#rem action = Description = This action saves the contents of the current Notebook page to a text file, first translating the page to [MediaWiki] markup. The user is prompted for the file name. The saved text is suitable for pasting into a [MediaWiki] page. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961789 #-------------------------------------------------- # export-this-page-as-plain-text page export-this-page-as-plain-text {#rem action = Description = This action saves the contents of the current Notebook page to a text file, first formatting it nicely as plain text. The user is prompted for the file name. The saved text is suitable for pasting into an e-mail message. See [Exporting Notebook Pages] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961791 #-------------------------------------------------- # export-this-page-as-raw-markup page export-this-page-as-raw-markup {#rem action = Description = This action saves the contents of the current Notebook page to a text file, first formatting it nicely as plain text. The user is prompted for the file name. The saved text is suitable for pasting into an e-mail message. See [Exporting Notebook Pages] for more information. This action has no precisely equivalent [Notebook command]; instead, use the [export-this-page-as] command.} 1114961794 #-------------------------------------------------- # exportformat page exportformat {#rem command = Syntax = exportformat = Description = Whenever Notebook is [expanding|Embedded Macro] and formatting a page, either for display or for [export|Exporting Notebook Pages], this command returns the name of the export format. This allows [Embedded Macro]s to tailor their behavior to the specific export format. See [Exporting Notebook Pages] for more information. The possible return values are as follows: * notebook: The page is being formatted for display by Notebook itself. * html-page: The page is being formatted as a complete HTML page. * html-text: The page is being formatted as HTML text, suitable for inclusion in an HTML page. * plain: The page is being formatted as plain text, suitable for inclusion in an e-mail message. * mediawiki: The page's expanded markup is being translated to [MediaWiki] markup. * expanded: The page is being formatted as [Notebook markup] with all [embedded macro]s expanded. * raw: The page is being formatted as raw [Notebook markup], just as you'd see it in the [Page Editor]. = Examples = #pre proc smartMacro {} { return "This page is formatted as [exportformat]." } #unpre = Implementation = [@showproc exportformat@] = See Also = [@linktable { copy-page-as copy-this-page-as export-page-as export-this-page-as formatas }@]} 1115584372 #-------------------------------------------------- # Exporting a Notebook to HTML page {Exporting a Notebook to HTML} {The entire contents of a Notebook file can be exported to HTML in one of two ways: as a single HTML file, or as a set of HTML files, one per Notebook page. The conversion of Notebook markup to HTML is done just as when exporting a page as html-text, with these differences: * Page links become HTML hyperlinks * Navigation aids are added. This export capability is still very bare-bones; if there are enhancements you'd like to see, please post them at the [Notebook Wiki]. = Single HTML File = To export your Notebook file as a single HTML file, select File / Export / As Single HTML File... from the main menu, or activate the [export-notebook-as-html-file] [action|user interface action] from the status line. = HTML File Set = To export your Notebook file as a set of HTML files, one per page, select File / Export / As Set of HTML Files... from the main menu, or activate the [export-notebook-as-html-set] [action|user interface action] from the status line. = For More Information = See [Exporting Notebook Pages] and [Exporting a Page to HTML].} 1113449567 #-------------------------------------------------- # Exporting a Page to HTML page {Exporting a Page to HTML} {Notebook pages can be exported to HTML in several ways (see [Exporting Notebook Pages] and [Exporting Entire Notebook Files] for important background material): * A single page can be exported or copied to the clipboard as a single HTML file. * A single page can be exported or copied to the clipboard as HTML text, suitable for pasting into a larger HTML file. * The entire Notebook can be exported as a single HTML file, with hyperlinks between the pages. * The entire Notebook can be exported as a set of HTML files, one per Notebook page, with hyperlinks between the pages. Regardless of the method is used, there are some strategies that carry over, especially if the HTML output is to be used "as is", rather than as the basis for further editing. = Export Formats and Embedded Macros = For example, it will often be the case that you'd like to have different things appear on a page when displayed in your notebook than on a webpage. If you have a [Daily Log], for example, the daily entries include [magic button]s labeled "Edit" and "View". HTML has no equivalent to Notebook's "Edit" capability, and the "View" button could be replaced in HTML by a standard page link. It's easy to build a page that varies based on where it's being exported by using [embedded macro]s and the [exportformat] command. Here's a simple example: #pre proc entry_buttons {topage} { if {[string match "html-*" [exportformat]]} { return "(\[View|$topage\])" } else { return "(\[View|$topage\], \[%Edit|edit-page [list $topage]\%]" } } #unpre = Preformatted HTML = When writing HTML-aware macros, you'll sometimes want to expand them directly to HTML, instead of expanding to Notebook markup for Notebook to convert to HTML. Suppose, for example, you want to use HTML's tag to mark a span of text in some. The difficult is that Notebook doesn't recognize arbitrary HTML tags, and assumes that it should convert the "<" and ">" characters to the HTML &lt; and &gt; attributes so that they'll display as is. This, clearly, is not what you want. There are two ways around it. == The ... Tags == Within a paragraph, you can tag a span of text as HTML, like this: #pre This is special text #unpre The <html> and </html> tags are not displayed by Notebook, and are completely ignored except when the page is being exported to some form of HTML. In this case, the tagged text is exported to HTML mostly unchanged--that is, page links and so forth are converted, but the "<" and ">" characters are left alone. Because these tags are ignored most of the time it's safe to use them in ordinary Notebook pages. == The #data html...#undata Directives == If you've got a large block of HTML text you'd like to export unchanged, you can use the [#data]...[#undata] directives to bracket it as an HTML data block. The text will be passed to the HTML output '''unchanged in any way.''' Consider the following: #pre #data html [Not a Page Link] #undata #unpre If this HTML data block were used in a page, Notebook would display it like this: #data html [Not a Page Link] #undata In other words, normal Notebook markup is completely ignored within an HTML data block. For this reason, HTML data blocks are usually produced by an [embedded macro], and only when the [export format|Exporting Notebook Pages] is html-file or html-text.} 1114287964 #-------------------------------------------------- # Exporting Entire Notebook Files page {Exporting Entire Notebook Files} {Although Notebook understands a number of [export formats|Exporting Notebook Pages], it is only possible at present to export the entire contents of a Notebook as HTML. See [Exporting a Notebook to HTML] for more details.} 1113449496 #-------------------------------------------------- # Exporting Notebook Pages page {Exporting Notebook Pages} {Individual Notebook pages can be exported in two ways--by copying the page's text to the clipboard using the Copy Page submenu of the [Edit Menu], or by saving the page's text to a file using the Export submenu of the [Page Menu]. = Export Formats = Pages can be exported in any of the following formats: raw: The exported text is the raw markup of the page, just as you'd see it and edit it in the [Page Editor]. This is appropriate for copying a page from one Notebook to another. expanded: Expanded markup is just like raw markup except that all embedded macros have been expanded. plain: Notebook expands and formats the page as prettily as it can as plain text. Header text is formatted as capital letters; the other text styles are ignored. Magic buttons are discarded, and of course there are no page links. This is appropriate for copying a page into an e-mail message. html-page, html-text: Notebook does its best to format the page in HTML. All text styles are honored, but magic buttons are discarded and there are no page links. There are two options for HTML output--as HTML body text, suitable for pasting into a longer HTML document, and as a standalone HTML page. See [Exporting a Page to HTML] for more details. mediawiki: Notebook translates the page's expanded markup into [MediaWiki] markup, suitable for pasting into the [Notebook Wiki]. = Export Formats and Embedded Macros = By using the [exportformat] command in an [embedded macro], you can write Notebook pages that expand to different markup depending on the destination. For example, here's an embedded macro that expands to a page link if the page will be displayed by Notebook, but capitalizes the page name if the page is being exported as plain text: #pre proc pagelink {page} { if {[exportformat] eq "plain"} { return [string toupper $page] } else { return "\[$page\]" } } #unpre See [Exporting a Page to HTML] for more examples. = Related Notebook Commands = There are a number of [Notebook Commands] which are related to exporting pages: [@linktable { copy-page-as copy-this-page-as exportformat export-page-as export-this-page-as formatas }@]} 1114297247 #-------------------------------------------------- # File Menu page {File Menu} {The File menu has the following items; the related [User Interface Action] is listed after each in parentheses. * File / New Window ([new-window])
Opens a new browser window on the current notebook file. * File / New Notebook... ([new-notebook])
Prompts the user to create a new notebook file in a new browser window. * File / Open Notebook... ([open-notebook])
Prompts the user to open an existing notebook file in a new browser window. * File / Preferences ([edit-preferences])
Pops up the [User Preferences] dialog, allowing you to select fonts, colors, and so forth. * File / Export / As Single HTML File... ([export-notebook-as-html-file])
Saves the contents of the notebook file as a single HTML page with page links, prompting for the file name. * File / Export / As Set of HTML Files... ([export-notebook-as-html-set])
Saves the contents of the notebook file as a set of interlinked HTML pages, one file per notebook page. Notebook prompts the user to select a destination directory for the files; if the directory is not empty, Notebook prompts to confirm that the Notebook should really be exported there. See [Exporting Notebooks to HTML] for more information. * File / Close Window ([close-window])
Closes the current window, and exits the application if it's the last one. * File / Invoke Action... ([request-action])
Prompts the user for the name of a [User Interface Action] and invokes it. See [User Interface Actions] for a complete list of actions. * File / Console (Windows Only)
Pops up an interactive console. * File / Exit
Exits the program.} 1114966603 #-------------------------------------------------- # find-again page find-again {#rem command #rem action = Syntax = find-again = Description = This command can be invoked as a [User Interface Action]. While editing, searches again for the string last found using [find-string]. It's equivalent to selecting Edit/Find Again from the application menu. = Examples = [find-string] can be used to add a "Find Again" item to the [editmenu]. = Implementation = [@showproc find-again@]} 1115584388 #-------------------------------------------------- # find-string page find-string {#rem command #rem action = Syntax = find-string ?''string''? = Description = This command can be invoked as a [User Interface Action]. Called without an argument, moves the cursor to the [Search Box] so that you can enter a new search string; this is equivalent to selecting Edit/Find from the application menu. If ''string'' is given, Notebook will enter it into the [Search Box] as though it had been typed by hand. Further, if you're in the [page editor] the cursor will be moved to the next occurrence of the ''string''. = Examples = [find-string] is most useful as an item on the [editmenu]. = Implementation = [@showproc find-string@]} 1116796610 #-------------------------------------------------- # Finding your way around page {Finding your way around} {You can find pages in your notebook in several ways. * By clicking on links, starting from your Home page, until you find your page. Usually you'll put links to your most important pages on your Home page. : If you click on a link to a page that doesn't exist yet, you'll be asked if you want to create it. If you say yes, you'll be taken to the Editor. See [Editing an existing page] for more. * By pressing the "Home" button on the toolbar. This button has a picture of a house. This takes you back to your Home page. * By pressing the "Index" button on the toolbar. The "Index" button has a picture of a book on it. This opens the [Index Sidebar], which will list all of the pages in your notebook in alphabetical order. Double-Click on any page in the list to go there. * By typing a word or phrase in the [Search Box] at the top of the Notebook window, and pressing Enter. This opens the [Index Sidebar], which will list all of the pages in your notebook that contain the word or phrase you entered. Double-click on any page in the list to go there. * Click on the title of any page. This is just like typing the title into the [Search Box]: it opens the [Index Sidebar], which lists all of the pages in your notebook that refer to the title you clicked. * Click on the "left-arrow" button on the toolbar to return to the previous page. * After clicking on "left-arrow" button one or more times, you can click on the "right-arrow" button on the toolbar to go forward again. * The Page menu has many other options for moving around. You can step forward and backward through your pages in alphabetical order, or cycle through the pages you've most recently looked at.} 1114967941 #-------------------------------------------------- # Font Preferences page {Font Preferences} {Notebook uses many different fonts, each with its own specific purpose. On the Fonts tab of the Preferences window you can select the typefaces you prefer for each purpose: * Title Text: The font used for page titles. * Header1 Text: The font used use for level 1 [Section Headers]. * Header2 Text: The font used use for level 2 [Section Headers]. * Header3 Text: The font used use for level 3 [Section Headers], and also between <h>...</h> tags in a page's text. * Body Text: The font used for normal page text. * Mono Text: The font used for monospace and preformatted text, and also in the [page editor]. * Small Text: The font used between <s>...</s> tags in a page's text.} 1114288907 #-------------------------------------------------- # formatas page formatas {#rem command = Syntax = formatas ''format'' ''name'' ?''options...''? = Description = This command formats the contents of the named page according to the specified export format, and returns the formatted text. It is the basis for the commands [copy-page-as], [copy-this-page-as], [export-page-as], and [export-this-page-as], but extends this by allowing the caller to pass options to the specified export formatter. The options vary from one output format to another. == Formats == The formats are as follows; as yet, the options are TBD. notebook: The page is being formatted for display by Notebook itself. html-page: The page is being formatted as a complete HTML page. html-text: The page is being formatted as HTML text, suitable for inclusion in an HTML page. plain: The page is being formatted as plain text, suitable for inclusion in an e-mail message. mediawiki: The page's expanded markup is being translated to [MediaWiki] markup. expanded: The page is being formatted as [Notebook markup] with all [embedded macro]s expanded. raw: The page is being formatted as raw [Notebook markup], just as you'd see it in the [Page Editor]. = Examples = #pre set pagetext [formatas html-page "My Project"] #unpre = Implementation = [@showproc formatas@]} 1115584449 #-------------------------------------------------- # forward-page page forward-page {#rem command #rem action = Syntax = forward-page = Description = This command can be invoked as a [User Interface Action]. [forward-page] is the opposite of [back-page]; once you've done a [back-page] to step back a page, you can call [forward-page] to step forward again. Calling [forward-page] is equivalent to pressing the "forward" or "right arrow" button on the browser's toolbar. = Examples = As [notebook command], [forward-page] is most likely to be useful as an entry on the [usermenu]. = Implementation = [@showproc forward-page@]} 1115584466 #-------------------------------------------------- # getsavefile page getsavefile {#rem command = Syntax = getsavefile ?''filename''? ?''filetype''? ?''title''? = Description = Prompts the user for a file name using a standard "save file as" dialog box. The command takes three optional arguments: * filename
The default file name; defaults to the empty string. * filetype
The default file type; defaults to ".txt". * title
The dialog box title; defaults to "Save File As..." The command returns the chosen file name, or the empty string if the user cancels the operation. = Examples = #pre set filename [getsavefile "home.html" ".html" "Save Home Page As..."] if {$filename ne ""} { savefile $filename [formatas html-page "Home"] } #unpre = Implementation = [@showproc getsavefile@]} 1115584507 #-------------------------------------------------- # Getting Started with Notebook page {Getting Started with Notebook} {This Notebook application is a tool for creating and browsing notebooks. A notebook is a collection of pages. Each page has a unique title, and is dedicated to some topic of interest to you. The "Home" page is your main point of departure; you'll usually use it to list the major topics within your notebook. Notebook pages can be linked together in any way you like, like pages on a website, so that from any page you can immediately jump to any related page. The best way to get started using Notebook is by creating a new notebook and examining the pages that Notebook puts in it automatically; you should especially browse through the "Tour" pages. Once you've seen what Notebook can do, you should look through the next few [Basic Features]. Once you've mastered those, reading the [Advanced Features] and [Reference] pages will help you use Notebook to your best advantage.} 1114968022 #-------------------------------------------------- # goto-home page goto-home {#rem command #rem action = Syntax = goto-home = Description = This command can be invoked as a [User Interface Action]. While browsing, [goto-home] takes you back to your Home page. = Examples = Pressing the following [Magic Button] will take you to your Home page: #pre [%Home|goto-home%] #unpre = Implementation = [@showproc goto-home@]} 1115584533 #-------------------------------------------------- # goto-index page goto-index {#rem deprecated-command #rem deprecated-action NOTE: This command is deprecated. Do not use it in new code. See [show-index] instead. #--- = Syntax = goto-index = Description = This command can be invoked as a [User Interface Action]. While browsing, calling this command will cause the browser to display your Index page. = Examples = Pressing the following [magic button] will take you to the Index page. #pre [%Index|goto-index%] #unpre = Implementation = [@showproc goto-index@]} 1115584597 #-------------------------------------------------- # goto-next-page page goto-next-page {#rem command #rem action = Syntax = goto-next-page ?''name''? ?''pattern''? = Description = This command can be invoked as a [User Interface Action]. While browsing, calling goto-next-page with no arguments will take you to the page that follows the current page. If you specify a page name, then it will take you to the page that follows the specified page. By default, the ordering of pages is determined by the contents of the [Index Sidebar]. If the sidebar is displaying an alphabetical index of all pages in the notebook, goto-next-page will take you to the next page in alphabetical order. If the sidebar is displaying search results in time-sorted order, goto-next-page will take you to the next-most-recently-edited page in the list. Alternatively, you can go to the next page in a chosen set of pages by specifying a pattern which page names must match. This is independent of the contents of the [Search Box], and is always alphabetical. See also: [goto-previous-page], [nextpage] = Examples = Pressing the following magic button will take you to the next page (in alphabetical order) whose name contains the string "Cheese". #pre [%Next Cheese|goto-next-page [current] "*Cheese*"%] #unpre = Implementation = [@showproc goto-next-page@]} 1115584657 #-------------------------------------------------- # goto-page page goto-page {#rem command #rem action = Syntax = goto-page ?''name''? = Description = This command can be invoked as a [User Interface Action]. While browsing, displays the page called name. If no page name is given, Notebook will prompt the user to enter one. = Examples = The following [magic button] will display the page called "Fred": #pre [%Show Fred For Me|goto-page "Fred"%] #unpre = Implementation = [@showproc goto-page@]} 1115584679 #-------------------------------------------------- # goto-previous-page page goto-previous-page {#rem command #rem action = Syntax = goto-previous-page ?''page''? ?''pattern''? = Description = This command can be invoked as a [User Interface Action]. While browsing, calling goto-previous-page with no arguments will take you to the page that precedes the current page. If you specify a page name, then it will take you to the page that precedes the specified page. By default, the ordering of pages is determined by the contents of the [Index Sidebar]. If the sidebar is displaying an alphabetical index of all pages in the notebook, goto-next-page will take you to the previous page in alphabetical order. If the sidebar is displaying search results in time-sorted order, goto-next-page will take you to the prior page in the list. Alternatively, you can go to the previous page in a chosen set of pages by specifying a pattern which page names must match. This is independent of the contents of the [Search Box], and is always alphabetical. See also: [goto-next-page], [prevpage] = Examples = Pressing the following magic button will take you to the previous page whose name contains the string "Cheese". #pre [%Previous Cheese|goto-previous-page [current] "*Cheese*"%] #unpre = Implementation = [@showproc goto-previous-page@]} 1115584704 #-------------------------------------------------- # goto-recent-changes page goto-recent-changes {#rem deprecated-command #rem deprecated-action NOTE: This command is deprecated. Do not use it in new code. See [show-recent] instead. #--- = Syntax = goto-recent-changes = Description = This command can be invoked as a [User Interface Action]. While browsing, calling this command will cause the browser to display your Recent Changes page. = Examples = Pressing the following [magic button] would take you to the Recent Changes page. #pre [%Index|goto-recent-changes%] #unpre = Implementation = [@showproc goto-recent-changes@]} 1115584610 #-------------------------------------------------- # goto-user-code page goto-user-code {#rem command #rem action = Syntax = goto-user-code = Description = This command can be invoked as a [User Interface Action]. While browsing, calling this command will cause the browser to display your User Code page. = Examples = Pressing the following [magic button] would take you to the User Code page. #pre [%Index|goto-user-code%] #unpre = Implementation = [@showproc goto-user-code@]} 1115584715 #-------------------------------------------------- # Help page Help {Welcome to the Notebook on-line help system. Notebook is an application for saving notes, to-do lists, daily logs, and any other kind of textual information in a place where you can find it all again, and where related information is easily found. If you've never used Notebook before, try taking the "Tour" in the main Notebook window. Then you should read about the [Basic Features]. = Help Topics = * [Basic Features] * [Advanced Features] * [Reference] * [Release Notes] * [License] * [About Notebook]} 1114968056 #-------------------------------------------------- # Help Browser page {Help Browser} {You're using it right now to browse Notebook's on-line help material. The help browser is just like the [page browser] window you use to browse and edit your own notebooks, except that it's read-only. You can do the following things in the help browser: * Click on links to browse a different page. * Press the "Back" button to go back to the previous page. * Press the "Home" button to go to the main Help page. * Press the "Index" button, and select a topic from the Help index in the [Index Sidebar]. * Enter a search string in the [Search Box], and select a topic from the search results in the [Index Sidebar].} 1114968085 #-------------------------------------------------- # Help Menu page {Help Menu} {The Help menu has the following items; the related [User Interface Action] is listed after each in parentheses. * Help / Notebook Help ([help-introduction])
Pops up the [help browser] and displays the main help page. * Help / Index ([help-index])
Pops up the [help browser] and displays the main help page; it also opens an alphabetical list of all of the available help topics in the [help browser]'s [Index Sidebar]. * Help / Topic... ([help-on])
Prompts the user to enter a help topic, and then displays it in the [help browser]. If the desired topic doesn't have a page of its own, the [help browser] will display a list of the pages that refer to it. * Help / Notebook Commands ([help-on-commands])
Pops up the [help browser], and displays a list of all of the [Notebook Commands] with links to their individual help pages. * Help / User Interface Actions ([help-on-actions])
Pops up the [help browser], and displays a list of all of the [User Interface Actions] with links to their individual help pages. * Help / Notebook Markup ([help-on-markup])
Pops up the [help browser], and displays a summary of Notebook's text markup conventions. * Help / License ([notebook-license])
Pops up the [help browser], and displays Notebook's licensing terms. (It's a standard BSD-style license.) * Help / Release Notes For [@version@] ([notebook-release-notes])
Pops up the [help browser], and displays the release notes for the current version. This topic includes a list of changes since the previous version. * Help / About Notebook ([about-notebook])
Pops up the [help browser] and displays information about Notebook's author and the location of the Notebook home page.} 1114968537 #-------------------------------------------------- # help-index page help-index {#rem command #rem action = Syntax = help-index = Description = This command may also be invoked as a [User Interface Action]. Displays the Help page in the [help browser], and opens an alphabetical index of the on-line help in the [Index Sidebar]. As such, it's equivalent to selecting the Index item from the [Help Menu]. = Examples = #pre help-index #unpre = Implementation = [@showproc help-index@]} 1115584738 #-------------------------------------------------- # help-introduction page help-introduction {#rem command #rem action = Syntax = help-introduction = Description = Displays the main Help page in the [help browser]. This action is equivalent to select the Help/Notebook Help menu item. = Examples = #pre help-introduction #unpre = Implementation = [@showproc help-introduction@]} 1115584771 #-------------------------------------------------- # help-on page help-on {#rem command #rem action = Syntax = help-on ?''topic''? = Description = This command can be invoked as a [User Interface Action]. Pops up the [help browser] and attempts to display the help page for the specified topic. If no topic is given, [help-on] prompts for a topic. If there is no help page for the chosen topic then [help-on] displays a list of the help pages which refer to it. = Examples = If you were to put the following [magic button] in one of your pages, then clicking on it would display this very help page: #pre [%Help on help-on|help-on help-on%] #unpre On the other hand, if you were to put this [magic button] in one of your pages, then clicking on it would display all of the help pages which refer to Cheese: #pre [%Help on Cheese|help-on Cheese%] #unpre = Implementation = [@showproc help-on@]} 1115584788 #-------------------------------------------------- # help-on-actions page help-on-actions {#rem command #rem action = Syntax = help-on-actions = Description = Displays the [User Interface Actions] page in the [help browser]. This action is equivalent to selecting the Help/User Interface Actions menu item. = Examples = #pre help-on-actions #unpre = Implementation = [@showproc help-on-actions@]} 1115584808 #-------------------------------------------------- # help-on-commands page help-on-commands {#rem command #rem action = Syntax = help-on-commands = Description = Displays the [Notebook Commands] page in the [help browser]. This action is equivalent to selecting the Help/Notebook Commands menu item. = Examples = #pre help-on-commands #unpre = Implementation = [@showproc help-on-commands@]} 1115584824 #-------------------------------------------------- # help-on-markup page help-on-markup {#rem command #rem action = Syntax = help-on-markup = Description = Displays the [Notebook Markup] page in the [help browser]. This action is equivalent to selecting the Help/Notebook Markup menu item. = Examples = #pre help-on-markup #unpre = Implementation = [@showproc help-on-markup@]} 1115584835 #-------------------------------------------------- # helpbtn page helpbtn {#rem command = Syntax = [@signature helpbtn@] = Description = Creates a [magic button] that will show the named help page in the [help browser] using the [help-on] command. If helppage doesn't name a real page, the [help browser] will display a list of pages that contain the specified text. = Examples = Putting the following [embedded macro] in your page #pre [@lb@]helpbtn "Notebook Commands"[@rb@] #unpre is equivalent to the entering the following [magic button]: #pre [%Notebook Commands|help-on "Notebook Commands"%] #unpre = Implementation = [@showproc helpbtn@]} 1114961936 #-------------------------------------------------- # Home page Home {This is the on-line help for Notebook. * [Help] Topics * [About Notebook]} 1035772761 #-------------------------------------------------- # Indented Paragraph page {Indented Paragraph} {You can indent a paragraph by putting a colon (":") as its first character. Just as with [bulleted paragraph]s, the number of colons determines the level of indentation (up to 9). For example, if you type in the following (putting the first colon in the first column of the line), #pre :: This paragraph is indented two levels #unpre Then you get this: :: This paragraph is indented two levels. You can use indentation to create topic lists. Put the topic on the first line, and maybe put it in boldface (see [Text Styles]); then, indent the description. In other words, this #pre Fruitbats : Fruitbats are frequently found flying about frozen fjords..... #unpre gets you Fruitbats : Fruitbats are frequently found flying about frozen fjords.... You can also use the colon to add a second or third paragraph to a [bulleted paragraph] (although an [explicit line break] might be better). For example, this #pre * Bulleted paragraph : Continuation of bulleted paragraph #unpre gets you this: * Bulleted paragraph : Continuation of bulleted paragraph} 1114294569 #-------------------------------------------------- # Index page Index {[@pageIndex@]} 1026257630 #-------------------------------------------------- # Index Sidebar page {Index Sidebar} {The Index Sidebar opens up on the right-hand side of the browser window whenever Notebook needs to display a list of page titles, e.g., when the Index toolbar button is pressed, or a search string is entered in the [Search Box]. While browsing, you can double-click on any listed page to go to that page. To delete a set of pages, select their names in the Sidebar and then select the Page / Delete Pages... menu item. You'll be asked to confirm that you want to delete the pages, and if you say yes they'll be deleted for good. = Sidebar Controls = The sidebar can be controlled via the [Sidebar Menu], or by its own toolbar buttons: * The "A to Z" button sorts the contents of the Sidebar alphabetically. * The "clock" button sorts the contents of the Sidebar chronologically, from most-recently-edited to least-recently-edited. * The "left-triangle" button closes the Sidebar. Just under the Sidebar's toolbar it indicates the sort order and whether it is showing the full index or just search results. = Page Order = The Sidebar's content controls the effect of the [goto-next-page] and [goto-previous-page] [User Interface Actions], whether invoked from the [Page Menu] or by their keyboard shortcuts: Ctrl+N and Ctrl+P. In plain English, Ctrl+N and Ctrl-P take you to the next and previous page in the notebook, as defined by the content and sort-order of the Sidebar. This makes it really easy to step through the pages found in a search.} 1116795819 #-------------------------------------------------- # indexlist page indexlist {#rem command = Syntax = [@signature indexlist@] = Description = Given a list of page names, indexlist returns the markup for an index list: a bulleted list of page names and modification times. It's the basis for commands like [pageIndex] and [searchIndex]. = Examples = The following macro would expand to a pretty list of the pages whose names contain the word "Jabberwock": #pre [@lb@]indexlist [pages "*Jabberwock*"][@rb@] #unpre = Implementation = [@showproc indexlist@]} 1114961940 #-------------------------------------------------- # Inline Images page {Inline Images} {As of version 2.1.2, Notebook can display image files! Unfortunately there are some reasonably severe restrictions and caveats (which is why Notebook didn't have this capability ''until'' version 2.1.2). = Restrictions on Inline Images = By default, Notebook can only display "GIF" images. In order to display BMP, JPEG, PNG, and TIFF images as well, you'll need to acquire and install the [TkImg Extension]. Second, display of JPEG images, especially large JPEG images, is '''extremely slow'''. Really truly amazingly extremely slow, so slow you probably don't want to try it. This is due to a bug in the current version of either Tcl/Tk or the [TkImg Extension], I'm not sure which. In the meantime, we shall all just have to live with it. Third, Tcl/Tk has only minimal built-in support for resizing images. If you want to display an image that's really too large to fit on the page, you can specify a maximum width and height. Notebook will ensure that the displayed image is no larger than the maximum; but it might be smaller, and the image quality may suffer. It might be possible to mitigate some of these restrictions in future versions; the problem is, most of the solutions require platform-specific binary code, which I'm not really in a position to support. = Displaying Inline Images = To include an image in your page, you use the following markup: : &lb;!image fileName ?options...!&rb; The ''filename'' can be an absolute path name or a relative path name; if relative, it's assumed to be relative to the location of the Notebook file. For example, #pre [!image hello.gif!] #unpre will include an image called "hello.gif", which must be found in the same directory as the Notebook file, while in #pre [!image images/hello.gif!] #unpre the image must be found in the "images" directory, immediately below the directory containing the Notebook file. Note that forward slashes "/" work just fine as directory separators, even on Windows. = Image Options = You can add the following options after the image file name: -width pixels
-height pixels : These options set the maximum width and height for the displayed image. If necessary, the image will be reduced in size by subsampling every ''n''th pixel such that the new width and height are no bigger than those specified here. Note that the image height and width are always reduced proportionally, so it's often only necessary to specify one of these options. -padwidth pixels : This option is used to pad the left and right sides of the image by a specified number of pixels. -text altText : Specifies the alternate text for the image. This text is shown on the status line when you mouse over the image; it's also included when the page containing the image is exported to HTML.} 1115570603 #-------------------------------------------------- # insert page insert {#rem command = Syntax = insert ''string'' = Description = While editing, inserts string into the editor at the insertion point. = Examples = The following command, if called while editing, will insert a timestamp into the page you're editing. #pre proc insertTimestamp {} { set now [clock seconds] return [clock format $now -fmt "%H:%M:%S"] } #unpre Such a command could become an item on your [editmenu]. = Implementation = [@showproc insert@]} 1115584941 #-------------------------------------------------- # insert-page page insert-page {#rem command #rem action = Syntax = insert-page ?''name''? = Description = This command can be invoked as a [User Interface Action]. While editing, calling this command is equivalent to selecting Edit/Insert Page from the application menu. If name is given, the text of the named page will be inserted into the page you are editing at the insertion point. Otherwise, Notebook will prompt you for the name of a page to insert. = Examples = [insert-page] is especially useful on your [editmenu]. For example, you can create a number of "template" pages containing boilerplate you re-use frequently, and then add an "Insert" item to the [editmenu] for each: #pre editmenu { . . . "Insert My Template" {insert-page "My Template"} . . . } #unpre = Implementation = [@showproc insert-page@]} 1115584966 #-------------------------------------------------- # International Character Sets page {International Character Sets} {Notebook has full support for Unicode and international character sets. If you've got the font, Notebook has the required Unicode encoding. Select your desired fonts in the [Font Preferences] tab of the [Preferences window|User Preferences] and you're good to go.} 1111725813 #-------------------------------------------------- # License page License {This software is copyrighted by William H. Duquette. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files. The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license. } 1117486303 #-------------------------------------------------- # Link Bars page {Link Bars} {A "link bar" or "navigation bar" is a set of links placed concisely on one line, and often separated by vertical bars ("|"). It usually appears at the top or bottom of the page. The link text is often an abbreviation of the linked page name. If you have a number of pages devoted to a particular project, you can make navigating them easier by adding a link bar at the top of each page; the link bar should link to the most important project pages. = Creating a Link Bar = The easiest way to create a link bar is just to type it in. For example, #pre [Commands|Notebook Commands]|[Buttons|Magic Button] #unpre displays as [Commands|Notebook Commands]|[Buttons|Magic Button] Alternatively, you can use the [linkbar] command, which creates [magic button]s rather than normal page links; page links are better, though, as they get updated automatically when you rename a linked page. = Reusing a Link Bar on Several Pages = If you want to use a link bar on several pages (and you probably do), you don't want to have to type it fresh each time; the time will come when you want to add or delete a page, it should really be defined in one place. The best thing to do is to put the link bar on its own page, and then include it into the pages that need it using an [embedded macro]. Of course, you could simply define the link bar as an [embedded macro] to begin with; but if it has a page to itself it will get updated automatically if you rename one of the linked pages. So, suppose you've got a link bar on a page called "Link Bar: My Project". You can include it in any page you like using the following macro: #pre [@lb@]pageget "Link Bar: My Project"[@rb@] #unpre If that's too verbose, define a command just for this purpose: #pre proc projlinks {} { pageget "Link Bar: My Project" } #unpre Then you can include the link bar with this much short macro: #pre [@lb@]projlinks[@rb@] #unpre} 1114295924 #-------------------------------------------------- # linkbar page linkbar {#rem command = Syntax = [@signature linkbar@] = Description = Formats a "link bar" or "navigation bar" of magic buttons. Use it to create navigation aids to your more important pages. The linklist is a list of "label", "pagename" pairs. = Examples = For example, #pre [@lb@]linkbar {Commands "Notebook Commands" Buttons "Magic Button"}[@rb@] #unpre This macro expands to the following link bar: [@linkbar {Commands "Notebook Commands" Buttons "Magic Button"}@] The most usual way to use linkbar is by defining a new command on your User Code page, and then using that command as an [embedded macro] on the pages where you want the link bar to appear Judicious creation and use of link bars can make your Notebook easier to navigate; the one downside is that the links are [magic button]s, and therefore will not be renamed if the linked pages are renamed. See also [Link Bars]. = Implementation = [@showproc linkbar@]} 1114961946 #-------------------------------------------------- # load-page page load-page {#rem command #rem action = Syntax = load-page ?''name''? = Description = This command can be invoked as a [User Interface Action]. Loads your Tcl code from the named page; if no name is given, Notebook will prompt you for a page name. [load-page] only works for pages which contain the [#Tcl] directive. = Examples = If you write much "user code", your [User Code Page] will quickly become too large for comfort. The easiest solution is to create additional pages, and have your [User Code Page] load them explicitly. For example, suppose you write a new command called "insert-timestamp". You could put it on a page called "User Code: insert-timestamp", and add the following line to your [User Code Page] (following the [#Tcl] directive, of course): #pre load-page "User Code: insert-timestamp" #unpre Then, this new page will get loaded automatically when your [User Code Page] is loaded. = Implementation = [@showproc load-page@]} 1115584989 #-------------------------------------------------- # load-this-page page load-this-page {#rem command #rem action = Syntax = load-this-page = Description = This command can be invoked as a [User Interface Action]. Loads any Tcl code defined following a [#Tcl] directive on the current page. = Examples = See [load-page] for more information; [load-this-page] is essentially the same as #pre load-page [current] #unpre = Implementation = [@showproc load-this-page@]} 1115589725 #-------------------------------------------------- # load-user-code page load-user-code {#rem command #rem action = Syntax = load-user-code = Description = This command can be invoked as a [User Interface Action]. Reloads the Tcl code on your [User Code Page]. Calling this command is equivalent to selecting Magic/Load User Code from the application menu. = Examples = See [load-page] for more details. = Implementation = [@showproc load-user-code@]} 1115589743 #-------------------------------------------------- # logentry page logentry {#rem command = Syntax = [@signature logentry@] = Description = This [embedded macro] marks the current page as an entry in the daily log whose main page is called logname. The date argument indicates which entry it is; it must have the form "yyyy-mm-dd" where "yyyy" is the year, "mm" is the month, 01-12, and "dd" is the day of the month, 01-31. This macro is seldom entered manually into a page; it's inserted into each day's new entry automatically when the "Edit Today's Entry" button is pushed. = Examples = See [Creating a Daily Log] for more. = Implementation = [@showproc logentry@]} 1114962008 #-------------------------------------------------- # logpage page logpage {#rem command = Syntax = [@signature logpage@] = Description = Included as an [embedded macro], this command turns the page into a [Daily Log]. The first seven log entries are displayed in their entirety; older pages are listed by date. = Examples = See [Creating a Daily Log] for more information. = Implementation = [@showproc logpage@]} 1114962011 #-------------------------------------------------- # lshift page lshift {#rem command = Syntax = [@signature lshift@] = Description = Pops the first element from a Tcl list stored in listvar and returns it; the element is removed from the list. If the list is empty, returns the empty string. This command is useful in reading variable length argument lists. = Examples = Consider the following Tcl code: #pre set mylist {red green blue} set color [lshift mylist] #unpre The value of "color" will be "red", and the value of "mylist" will be {green blue}. = Implementation = [@showproc lshift@]} 1114962014 #-------------------------------------------------- # Magic Button page {Magic Button} {A Magic Button is a special kind of link. Instead of linking to another page, clicking on the Magic Button executes a command: one of the standard [Notebook Commands], or a command of your own from your [User Code Page]. Magic buttons are typed into a page like this: #pre [%Button Text|Command to Execute%] #unpre For example, the following Magic Button uses the [help-on] command to link to the main [Help] page while displaying the text "Notebook Help": #pre [%Notebook Help|help-on Help%] #unpre If you put this in a page, it would look like this: [%Notebook Help|help-on Help%]. As you can see, it looks like a link, but a link of a different color.} 1114296377 #-------------------------------------------------- # Magic Menu page {Magic Menu} {This menu gives you access to Notebook's extensibility features. It has the following items; the related [User Interface Action] is listed after each in parentheses. * Magic / Go To User Code ([goto-user-code])
While browsing, takes you to your [User Code Page]. See [Defining New Commands]. * Magic / Load This Page ([load-this-page])
Loads all Tcl code from the current page. If you're currently editing the page, Notebook saves your edits before loading the code. * Magic / Load Page... ([load-page])
Prompts for a page name, and then loads all Tcl code from that page. * Magic / Load User Code ([load-user-code])
Loads all Tcl code from your [User Code Page]. * Magic / Expand Macros?
Toggles the expansion of [embedded macro]s on and off. Expansion is on by default; turn it off if you think you've added an [embedded macro] that's causing you problems.} 1114966636 #-------------------------------------------------- # Markup Quick Reference page {Markup Quick Reference} {= Paragraphs = * Paragraphs of [preformatted text] begin with at least one space or tab, or with a [#pre] directive (see below). * [Bulleted paragraph]s begin with 1 to 9 "*" characters. * [Indented paragraph]s begin with 1 to 9 ":" characters. * Normal paragraphs begin with anything else, usually after a blank line. * <br> causes an [explicit line break] within the current paragraph. * A line beginning with "-" causes an [explicit line break] and a new paragraph. = Text Styles = All text styles are available using HTML-like tags. * <h>...</h> -- Inline Header * <b>...</b> -- Boldface * <i>...</i> -- Italics * <m>...</m> -- Monospace * <s>...</s> -- Small Type * <x>...</x> -- Strikeout Bold and italics can also be entered using traditional Wiki-like markup: #pre '''Bold''', ''Italic'', '''''Bold and Italic''''' #unpre '''Bold''', ''Italic'', '''''Bold and Italic''''' See also [Text Styles]. = Links and Magic = * &lb;Page Name&rb; -- [Creating links to other pages] * &lb;Link Text|Page Name&rb; -- [Creating links to other pages] * &lb;@command...@&rb; -- [Embedded Macro] * &lb;%Name|command%&rb; -- [Magic Button] = Directives = * [#---] -- Draws a horizontal line across the page. * [#rem] -- Add undisplayed remarks (comments) to a page. * [#meta] -- Define page-specific options. * [#pre]...[#unpre] -- Bracket a block of preformatted text. * [#Tcl]...[#unTcl] -- Bracket a block of Tcl code. * [#data]...[#undata] -- Bracket a block of arbitrary data. See also [Directives]. = Section Headers = * = Header1 Text = -- A first-level header * == Header2 Text == -- A second-level header * === Header3 Text === -- A third-level header See also [Section Headers]. = HTML Support = * <html>...</html> -- In-line HTML pass-through. * [#data] html...[#undata] -- Bracket a block of HTML text for pass-through. See also [Exporting A Page to HTML]} 1115584900 #-------------------------------------------------- # MediaWiki page MediaWiki {MediaWiki is the software that runs the [Notebook Wiki] website; it was developed to support the Wikipedia project. MediaWiki markup is similar but not identical to Notebook's own markup, as both were greatly influenced by UseMod Wiki. The [Notebook Wiki] uses the [MediaWiki] software; for convenience, Notebook supports [MediaWiki] markup as one of its [export formats|Exporting Notebook Pages].} 1113323519 #-------------------------------------------------- # Message Log page {Message Log} {The Message Log displays all of the messages written to the status line of every Notebook window. New messages appear at the top, and scroll down. In addition, if Notebook should detect a programming error (in its own code or in User Code) a full stack trace is written to the Message Log as well. Your code can write messages to the status line (and thus to the Message Log) using the [msg] command; this is often useful for debugging. You can display the Message Log at any time by selecting the Window/Message Log menu item.} 1072804301 #-------------------------------------------------- # message-log page message-log {#rem command #rem action = Syntax = message-log = Description = Pops up the [Message Log] window. This action is equivalent to selecting the Window/Message Log menu item. = Examples = #pre message-log #unpre = Implementation = [@showproc message-log@]} 1115585027 #-------------------------------------------------- # Miscellaneous Preferences page {Miscellaneous Preferences} {The Miscellaneous tab of the [User Preferences] dialog box contains the following options, which can be turned on or off by clicking in the check box: Include "Tour" and other introductory material in new notebook files: If this option is checked (as it is by default), then the introductory material will be included in any new Notebook files you create. If it is not checked, the new Notebook files will contain a minimal set of pages, including Home, Index, Search, Recent Changes, and User Code. Begin editing with the cursor at the bottom of the page: If this option is checked, then whenever you edit a page in the [Page Editor] the cursor will initially be positioned at the bottom of the page. Otherwise, the cursor will initially be positioned at the top of the page (the default). Note that in all versions of Notebook prior to 2.1.1 the cursor was always positioned at the bottom of the page. Display "#" directives in the Page Browser: By default, "#" [directives] are not displayed by the page browser except via their side-effects, e.g., the lines between [#pre] and [#unpre] are displayed as preformatted text. If this option is checked, then all "#" [directives] will be displayed. Create new pages on link click without prompting: If you click on a link to a nonexistent page, Notebook will normally tell you that the page doesn't exist and ask if you'd like to create it. If this option is checked, Notebook will assume that you'd like to create the page and will take you directly to the [page editor] without any prompting. Open the Index Sidebar at startup: If this is checked, the [Index Sidebar] will be opened automatically for each [Page Browser] window. Otherwise (the default) the [Index Sidebar] will be opened only on request, e.g., to display search results. Use Incremental Search by default: If this is checked (the default), the search results will be updated and displayed with each character entered in the [Search Box]. Otherwise, the search results will be displayed only when your press Enter in the [Search Box]. Note that this setting may be changed temporarily on the [Search Box]'s pull-down. Search both page titles and content by default: If this is checked (the default), any text entered in the [Search Box] will be matched against both the title and content of each page; otherwise, only page titles will be matched. Note that this setting may be changed temporarily on the [Search Box]'s pull-down.} 1114967280 #-------------------------------------------------- # msg page msg {#rem command = Syntax = msg ''text'' = Description = Writes the specified text to the [Message Log]; in addition, the first line of text will appear in the window's status line. Your [notebook commands] can use [msg] to tell you things; it's also useful for debugging. = Examples = Pressing the following magic button would write "Hello!" to the status line: #pre [%Greet Me|msg "Hello!"%] #unpre = Implementation = [@showproc msg@]} 1115585047 #-------------------------------------------------- # new-notebook page new-notebook {#rem command #rem action = Syntax = new-notebook = Description = Prompts the user to create a new notebook file in a new window. This action is equivalent to the File/New Notebook menu item. = Examples = #pre new-notebook #unpre = Implementation = [@showproc new-notebook@]} 1115585063 #-------------------------------------------------- # new-window page new-window {#rem command #rem action = Syntax = new-window = Description = Opens a new browser window on the current notebook file. This action is equivalent to the File/New Window menu item. = Examples = #pre new-window #unpre = Implementation = [@showproc new-window@]} 1115585079 #-------------------------------------------------- # newpage page newpage {#rem command = Syntax = newpage ''name'' ?''template''? = Description = Creates a new page called name, which contains the specified text, and returns the name. The page is not displayed; to create and display the new page, use [goto-page]. = Examples = The following code creates a new page called "My New Page", which will initially contain the string "My Template Text", and then displays it. #pre goto-page [newpage "My New Page" "My template text"] #unpre = Implementation = [@showproc newpage@]} 1115585105 #-------------------------------------------------- # nextpage page nextpage {#rem command = Syntax = nextpage ''?page?'' ''?pattern?'' = Description = Returns the name of the page that follows the specified page; name defaults to the current page. By default, the ordering of pages is determined by the contents of the [Index Sidebar]. If the sidebar is displaying an alphabetical index of all pages in the notebook, nextpage will return the name of the next page in alphabetical order. If the sidebar is displaying search results in time-sorted order, nextpage will return the name of the next-most-recently-edited page in the list. Alternatively, you can specify a pattern which page names must match. This is independent of the contents of the [Search Box], and is always alphabetical. See also: [prevpage], [goto-next-page]. = Examples = For example, the following command returns the name of the page that follows "Nacho Cheese" in the set of pages that have "Cheese" in their names: #pre nextpage "Nacho Cheese" "*Cheese*" #unpre If there is no subsequent page in the chosen set, nextpage returns the empty string. = Implementation = [@showproc nextpage@]} 1115585127 #-------------------------------------------------- # Notebook Command page {Notebook Command} {A Notebook Command is a special command that you can use in [Embedded Macro] or [Magic Button] to make Notebook do what you want it to do. See [Notebook Commands] for a list of the standard ones; you can write your own in [the Tcl language].} 1029184887 #-------------------------------------------------- # Notebook Commands page {Notebook Commands} {The following commands can be used in [Embedded Macro]s and [Magic Button]s; you can also write new commands in [the Tcl language]. Many of these commands are also [User Interface Actions]. See also [Deprecated Notebook Commands]. [@linktable { about-notebook askfor assert back-page cancel-edits clipboard close-window codeget copy-page-as copy-string copy-this-page-as current cut-string cycle-recent-pages dbfile dbsave delete-page delete-pages editmenu edit-page edit-preferences edit-this-page edittodayslog exportformat export-page-as export-this-page-as find-string find-again formatas forward-page getsavefile goto-home goto-next-page goto-page goto-previous-page goto-user-code helpbtn help-index help-introduction help-on help-on-actions help-on-commands help-on-markup indexlist insert insert-page linkbar load-page load-this-page load-user-code logentry logpage lshift message-log msg newpage new-notebook new-window nextpage notebook-license notebook-release-notes open-notebook pagedelete pageexists pageexpand pageget pageIndex pages pagesbytime pagesearch pageset pagetime parse paste-string prevpage recentChanges redo-change refresh-this-page rename-page rename-this-page replace-string request request-action require save-and-continue save-edits savefile searchIndex searchtext showsearch show-index show-recent show-version sidebar sidebar-byname sidebar-bytime sidebar-close sidebar-open super template tsubst undo-change usermenu version }@]} 1116795315 #-------------------------------------------------- # Notebook Markup page {Notebook Markup} {Unlike most word processors, Notebook is not "WYSIWYG": What You See isn't exactly What You Get. WYSIWYG is very nice when you're trying to precisely control the printed output, but it makes a number of things much harder--like inserting links to other pages. Consequently, Notebook lets you edit a page as plain text, with a few simple conventions for indenting, creating headers and bulleted lists, and adding links to other pages. For the most part, you type block paragraphs like you normally would: a paragraph is just a sequence of lines ending with a blank line. You can type carriage returns yourself, or just let the text wrap; either way, Notebook will wrap the text nicely while you're browsing. You can do many other things, too: * [Markup Quick Reference] * [Section Headers] * [Bulleted Paragraph] * [Indented Paragraph] * [Explicit Line Break] * [Text Styles] * [Preformatted Text] * [Creating links to other pages] * [Special Characters] * [Inline Images] * [Directives] * [Embedded Macro]s * [Magic Button]s} 1114361693 #-------------------------------------------------- # Notebook Wiki page {Notebook Wiki} {The Notebook Wiki is the Notebook's home page on the World Wide Web. On it you'll find Notebook downloads, release notes, documentation, bug reports, feature requests, user-contributed enhancements, and more. The web address is: : http://notebook.wjduquette.com} 1114297277 #-------------------------------------------------- # notebook-license page notebook-license {#rem command #rem action = Syntax = notebook-license = Description = Displays Notebook's licensing terms in the [help browser]. This action is equivalent to the Help/License menu item. = Examples = #pre notebook-license #unpre = Implementation = [@showproc notebook-license@]} 1115585137 #-------------------------------------------------- # notebook-release-notes page notebook-release-notes {#rem command #rem action = Syntax = notebook-release-notes = Description = Displays the release notes for the current version of Notebook in the [help browser]; this includes a list of changes since the previous version. This action is equivalent to the Help/Release Notes For [@version@] menu item. = Examples = #pre notebook-release-notes #unpre = Implementation = [@showproc notebook-release-notes@]} 1115585145 #-------------------------------------------------- # open-notebook page open-notebook {#rem command #rem action = Syntax = open-notebook = Description = Prompts the user to open an existing notebook file in a new window. This action is equivalent to the '''File/Open''' Notebook menu item. = Examples = #pre open-notebook #unpre = Implementation = [@showproc open-notebook@]} 1115585162 #-------------------------------------------------- # Page Browser page {Page Browser} {= Overview = The page browser is where you'll spend much of your time using Notebook. This is where pages are displayed, and where you navigate to other pages. The page browser contains the following things: * The browser pane and scrollbar. The browser pane is where the contents of pages is actually displayed. * The tool bar, which contains the following tools: ** The "left arrow" or "Back" button, which returns you to the previous browsed page. ** The "right arrow" or "Forward" button, which takes you forward again after going back. ** The "Home" button, which returns you to the notebook's Home page. ** The date and time when the current page was last edited. ** The "Edit" button, which loads the current page into the [page editor]. ** The "book" or "Index" button, which displays in the [Index Sidebar] a complete index of the notebook's pages. ** The [Search Box]. Type any string into a the Search field, and Notebook will show you a list in the [Index Sidebar] of all pages that contain that string. It will also highlight any occurrences of the string in the current page. * The [Index Sidebar], which is used to list the page index and search results. The [Index Sidebar] may be open or closed; if closed, it will open automatically when it's needed. = Recent Pages Menu = Shift-clicking in the browser window (pressing Shift while clicking the left mouse button) pops up the Recent Pages menu. This lists the pages you've most recently browsed; click on any one of them to go to it. = User Menu = Right-clicking or Control-clicking in the browser menu pops up the User Menu, which is a place for you to put your own [Notebook Command]s. See [Defining new commands] and [usermenu] for more information. = Key Commands = The menu bar contains many items that apply to the page browser; many of these have shortcut keys assigned to them. Take a look at the menus to see what shortcut keys are available to you.} 1114968917 #-------------------------------------------------- # Page Editor page {Page Editor} {= Overview = When you're not browsing pages in the [page browser], you'll likely be editing one in the page editor. The page editor consists of the following things: * The editing pane itself, with its scrollbar. * A toolbar which contains the following buttons, from left to right: ** The "disk" or "Save" button, which saves your edits but lets you continue editing. ** The "Cut" button, which cuts the selected text to the clipboard. ** The "Copy" button, which copies the selected text to the clipboard. ** The "Paste" button, which pastes the text from the clipboard into the editor. ** The "Undo" button, which undoes the last set of edits. ** The "Redo" button, which undoes the last Undo. ** The "checkmark" or "Done" button, which saves your edits and returns to the [page browser]. You can also press Ctrl+S. ** The "X" or "Cancel" button, which cancels your edits and returns to the [page browser]. You can also press Escape. ** The "book" or "Index" button, which displays in the [Index Sidebar] a complete index of the notebook's pages. ** The [Search Box]. Type any string into a the Search field, and Notebook will show you a list in the [Index Sidebar] of all pages that contain that string. It will also highlight any occurrences of the string in the current page. * The [Index Sidebar], which is used to list the page index and search results. The [Index Sidebar] may be open or closed; if closed, it will open automatically when it's needed. = Key Commands = The menu bar contains many items that apply to the editor; many of these have shortcut keys assigned to them. Take a look at the menus to see what shortcut keys are available to you. = Editor Preferences = While you're editing text, the editor will automatically wrap and indent lines for you. See the [Editor Preferences] page for more information.} 1114968957 #-------------------------------------------------- # Page Menu page {Page Menu} {The Page menu is used to navigate through the notebook, and to operate on individual pages. It contains the following items; the related [User Interface Action] is listed after each in parentheses. * Page / Export / As HTML Text ([export-page-as-html-text|export-page-as])
Formats the current page as HTML body text, suitable for pasting into an existing HTML page, and saves it to disk, prompting for the file name. See [Exporting a Page to HTML] for more information. * Page / Export / As an HTML Page ([export-page-as-html-page|export-page-as])
Formats the current page as a complete HTML page and saves it to disk, prompting for the file name. See [Exporting a Page to HTML] for more information. * Page / Export / As Plain Text ([export-page-as-plain-text|export-page-as])
Formats the current page as plain text, suitable for pasting into an e-mail message or text file, and saves it to disk, prompting for the file name. * Page / Export / As Expanded Markup ([export-page-as-expanded-markup|export-page-as])
Expands any [embedded macro]s in the current page and saves the resulting Notebook markup text to disk, prompting for the file name. * Page / Export / As Raw Markup ([export-page-as-raw-markup|export-page-as])
Saves the the raw markup of the current page to disk, prompting for the file name. * Page / Edit This Page ([edit-this-page])
Loads the current page's text into the [page editor]. * Page / Rename This Page... ([rename-this-page])
Prompts the user for a new name for the current page. All links to the page will be updated automatically, unless the new name differs from the old only by its capitalization. In that case, the new capitalization will be used when the page is displayed, but links will be unchanged. (Note that links are case-insensitive.) * Page / Refresh Page ([refresh-this-page])
Redisplays the current page. Usually, the effect isn't noticeable. * Page / Edit Page... ([edit-page])
Prompts the user for a page, and then loads it into the [page editor]. * Page / Rename Page... ([rename-page])
Prompts the user for a page, and then for a new name for that page. The page is then renamed as for Page/Rename This Page. * Page / Delete Page... ([delete-page])
Allows you to delete the current page. You will be asked for confirmation. Once the page is gone, it is gone. * Page / Delete Pages... ([delete-pages])
Allows you to delete the pages whose names are selected in the [Index Sidebar]. You will be asked for confirmation. Once the pages are gone, they are gone. * Page / Back Up One Page ([back-page])
Returns to the previously viewed page. * Page / Forward One Page ([forward-page])
Steps forward again after Page/Back Up One Page. * Page / Cycle Through Recent Pages ([cycle-recent-pages])
Cycles, one page a time, through the most recently viewed pages. * Page / Previous Page In Sidebar ([goto-previous-page])
Goes to the previous page in your notebook, as currently listed in the [Index Sidebar]. * Page / Next Page In Sidebar ([goto-next-page])
Goes to the next page in your notebook, as currently listed in the [Index Sidebar]. * Page / Go To Page... ([goto-page])
Prompts the user for a page, and then displays it. * Page / Go To Home ([goto-home])
Returns to the Home page. Identical to the "Home" button on the browser's tool bar.} 1116795705 #-------------------------------------------------- # pagedelete page pagedelete {#rem command = Syntax = [@signature pagedelete@] = Description = Deletes a specified page from the Notebook, but does not save the Notebook to disk. Because pagedelete doesn't save the Notebook, it's useful when deleting many pages at once; after all have been deleted, call [dbsave] to save the changes. In most ordinary circumstances, however, [delete-page] is a more appropriate choice. = Examples = The following magic button would cause the current page to be deleted and the Notebook saved. #pre [%Delete Me|pagedelete [current]; dbsave%] #unpre = Implementation = [@showproc pagedelete@]} 1114962029 #-------------------------------------------------- # pageexists page pageexists {#rem command = Syntax = [@signature pageexists@] = Description = Returns 1 if there's a page called name in the current notebook, and 0 otherwise. Note that the query is case-insensitive; if there's a page called "My Page", then #pre pageexists "my page" #unpre would return 1. = Examples = It's often useful to check whether a page exists before trying to do something with it. = Implementation = [@showproc pageexists@]} 1114962032 #-------------------------------------------------- # pageexpand page pageexpand {#rem command = Syntax = pageexpand ''name'' = Description = Retrieves the unformatted text of the named page, first expanding any [embedded macro]s. It's an error if the page doesn't exist. If any macro contains an error, it will appear unexpanded in the returned text. Note that this command will expand the page's macros regardless of the setting of the Magic/Expand Macros? menu item. See also [pageget]. Warning: this command expands the named page. Calling it from an [embedded macro] for the particular page in which the macro is embedded might cause Notebook to hang. = Examples = See the implementation of [logpage]. [logpage] uses [pageexpand] to retrieve each of the log entries. = Implementation = [@showproc pageexpand@]} 1115585185 #-------------------------------------------------- # pageget page pageget {#rem command = Syntax = [@signature pageget@] = Description = Retrieves the unformatted text of the named page, without expanding any [embedded macro]s. It is an error if the page doesn't exist. See also [pageexpand]. = Examples = The following command writes the raw text of the current page to a disk file called "file.out": #pre proc saveCurrentPage {} { set f [open file.out "w"] puts $f [pageget [current]] close $f } #unpre = Implementation = [@showproc pageget@]} 1114962038 #-------------------------------------------------- # pageIndex page pageIndex {#rem command = Syntax = [@signature pageIndex@] = Description = This [embedded macro] expands into a formatted alphabetic list of pages whose titles match the specified pattern, which can contain wildcard characters. If pattern is omitted, then the list will include every page in the notebook. See also [pages] and [indexlist]. = Examples = The standard [Index] page consists of the following embedded macro: #pre [@lb@]pageIndex[@rb@] #unpre The following macro expands into an index of the pages that contain the word "Cheese" in their title: #pre [@lb@]pageIndex *Cheese*[@rb@] #unpre The wildcard "*" characters are very important; without them, the only page the index would ever contain would be one called "Cheese". = Implementation = [@showproc pageIndex@]} 1114962040 #-------------------------------------------------- # pagerename page pagerename {#rem command = Syntax = [@signature pagerename@] = Description = Renames a specified page from the Notebook, but does not save the Notebook to disk. Because pagerename doesn't save the Notebook, it's useful when renaming many pages at once; after all have been renamed, call [dbsave] to save the changes. In most ordinary circumstances, however, [rename-page] is a more appropriate choice. = Implementation = [@showproc pagerename@]} 1114962043 #-------------------------------------------------- # pages page pages {#rem command = Syntax = [@signature pages@] = Description = If no pattern is given, [pages] returns an alphabetical list of the names of the pages in the notebook. The list is intended to be processed by additional commands; for example, indexlist will format it as a bulleted list. If pattern is given, only pages that match the pattern will be included. See also: [pageIndex], [indexlist], [pagesbytime]. = Examples = The following call will return a list of the pages whose names include the word "Lego": #pre pages "*Lego*" #unpre = Implementation = [@showproc pages@]} 1114962046 #-------------------------------------------------- # pagesbytime page pagesbytime {#rem command = Syntax = [@signature pagesbytime@] = Description = [pagesbytime] is equivalent to [pages], except that the pages are sorted from most recently edited to least recently edited instead of alphabetically. See also: [pageIndex], [indexlist], [pages]. = Examples = For example, the following call will return a list of the pages whose names include the word "Lego", in time-sorted order. #pre pagesbytime "*Lego*" #unpre = Implementation = [@showproc pagesbytime@]} 1114962049 #-------------------------------------------------- # pagesearch page pagesearch {#rem command = Syntax = [@signature pagesearch@] = Description = Returns a list of the names of the pages whose names or bodies contain the searchText. The names are in alphabetical order. The returned list is intended to be processed further; for example, indexlist will format it as a bulleted list. See also: [indexlist], [searchIndex], and [showsearch]; contrast with [pages] and [pageIndex]. = Examples = The following call returns a list of the pages whose name or body includes the word "Cheese": #pre pagesearch "Cheese" #unpre = Implementation = [@showproc pagesearch@]} 1114962052 #-------------------------------------------------- # pageset page pageset {#rem command = Syntax = [@signature pageset@] = Description = Sets the body text for page name to value. If the page already existed, value replaces its previous content; if the page didn't exist, it is created. Note that the change isn't saved to disk automatically; if you want to ensure that your change is saved, call [dbsave] afterwards. If you want to ensure that you're creating a new page and not overwriting the content of an existing page, use [newpage] instead of [pageset]. = Examples = Suppose you wanted to add a link to the bottom of a page, separated from the bulk of the page by a horizontal bar. The following code would do the trick: #pre set text [pageget "My Page"] append text "\n#---\n\[My New Link\]" pageset "My Page" $text dbsave #unpre = Implementation = [@showproc pageset@]} 1114962054 #-------------------------------------------------- # pagetime page pagetime {#rem command = Syntax = [@signature pagetime@] = Description = Returns the time the page was last edited. If format is omitted, the time will be expressed in standard Unix format, as the number of seconds since the epoch. If given, format is a Tcl "clock format" string, and the output will be a formatted time and or date. See the Tcl "clock" man page for full details. = Examples = The following command will format the Home page's last edit time as "MM/DD/YY HH:MM:SS", on a twenty-four-hour clock: #pre pagetime Home "%D %T" #unpre = Implementation = [@showproc pagetime@]} 1114962057 #-------------------------------------------------- # parse page parse {#rem command = Syntax = parse text = Description = This command parses a text string containing [Notebook Markup] and returns a tagged list containing the parsed text. I intend to document the tags and structure of the parsed text eventually, but for now it must remain TBD. Be warned: the structure of the parsed list is one of the things most likely to be modified from one version of Notebook to another, so use this command with care. = Examples = #pre set taglist [parse [pageexpand "Home"]] #unpre = Implementation = [@showproc parse@]} 1114962060 #-------------------------------------------------- # paste-string page paste-string {#rem command #rem action = Syntax = paste-string = Description = This command can be invoked as a [User Interface Action]. While you're editing a page, [paste-string] pastes the text from the clipboard into the editor. [paste-string] is most useful as an item on your [editmenu]. = Examples = Placed in your [User Code Page], the following code will define an editor context menu with a Paste item. #pre editmenu { Paste {paste-string} } #unpre = Implementation = [@showproc paste-string@]} 1115585205 #-------------------------------------------------- # Preformatted Text page {Preformatted Text} {Sometimes you want to type in some text and have it display just exactly as you typed it. Most of the examples in this [Notebook Markup] pages are entered as preformatted text, so that you can see how to type them. Also, preformatted text is always displayed in a monospace font, so that things like tables line up properly: Item $/Dozen =========== ======= Fruitbats $ 5.95 Armadillos $ 27.95 Chupacabras $199.94 There are two ways to enter preformatted text. The first way is to type a space (" ") as the first character of a paragraph. The preformatted paragraph will continue to the next blank link, [bulleted paragraph], or [indented paragraph]. By convention you should put a space (" ") at the beginning of each line of the paragraph, but this isn't strictly necessary. For longer blocks of preformatted text you can use the [#pre] and [#unpre] [directives] at the beginning and end of the block. Be aware that you can't put [text styles], links to other pages, or [magic button]s into a preformatted paragraph; [embedded macro]s, however, will be expanded as usual.} 1098501824 #-------------------------------------------------- # prevpage page prevpage {#rem command = Syntax = prevpage ?''page''? ?''pattern''? = Description = Returns the name of the page that precedes the specified page; name defaults to the current page. By default, the ordering of pages is determined by the contents of the [Index Sidebar]. If the sidebar is displaying an alphabetical index of all pages in the notebook, prevpage will return the name of the previous page in alphabetical order. If the sidebar is displaying search results in time-sorted order, prevpage will return the name of the prior page in the list. Alternatively, you can specify a pattern which page names must match. This is independent of the contents of the [Search Box], and is always alphabetical. See also: [nextpage], [goto-previous-page]. = Examples = For example, the following command returns the name of the page that precedes "Nacho Cheese" in the set of pages that have "Cheese" in their names: #pre prevpage "Nacho Cheese" "*Cheese*" #unpre If there is no previous page in the chosen set, prevpage returns the empty string. = Implementation = [@showproc prevpage@]} 1115585238 #-------------------------------------------------- # Recent Changes page {Recent Changes} {[@recentChanges@]} 1026526241 #-------------------------------------------------- # recentChanges page recentChanges {#rem command = Syntax = [@signature recentChanges@] = Description = This [embedded macro] expands into a formatted alphabetic list of pages whose titles match the specified pattern, which can contain wildcard characters. If pattern is omitted, then the list will include every page in the notebook. The pages are listed from most recently edited to least recently edited. See also [pages] and [indexlist]. = Examples = The standard [Recent Changes] page consists of the following embedded macro: #pre [@lb@]recentChanges[@rb@] #unpre The following macro expands into an index of the pages that contain the word "Cheese" in their title: #pre [@lb@]recentChanges *Cheese*[@rb@] #unpre The wildcard "*" characters are very important; without them, the only page the index would ever contain would be one called "Cheese". = Implementation = [@showproc recentChanges@]} 1114962066 #-------------------------------------------------- # redo-change page redo-change {#rem command #rem action = Syntax = redo-change = Description = This command can be invoked as a [User Interface Action]. While editing, calling [redo-change] will redo the last set of undone edits; it's equivalent to selecting Edit/Redo from the application menu. = Examples = [redo-change] is mostly useful as an item on your [editmenu]. = Implementation = [@showproc redo-change@]} 1115585249 #-------------------------------------------------- # Reference page Reference {[Markup Quick Reference] : A cheat sheet for Notebook's formatting rules and notations. Use this when you're editing a page. [Notebook Commands] : Documentation for each of Notebook's [embedded macro] and [magic button] commands. [User Interface Actions] : Actions accessible from the Notebook status line. [User Preferences] : Things you can change to suit you. [File Menu] -- [Edit Menu] -- [Page Menu] -- [Magic Menu] -- [Window Menu] -- [Help Menu] : Contents of each menu. [Page Browser] : Contents of the browser window while browsing pages. [Page Editor] : Contents of the browser window while editing pages. [Index Sidebar] : How to use the Index Sidebar to find pages. [Welcomer] : The "Welcome to Notebook" window. [Message Log] : The Message Log window.} 1114959008 #-------------------------------------------------- # refresh-this-page page refresh-this-page {#rem command #rem action = Syntax = refresh-this-page = Description = This command can be invoked as a [User Interface Action]. While browsing, causes the currently displayed page to be redisplayed. As such, it's roughly equivalent to #pre goto-page [current] #unpre = Examples = You might use [refresh-this-page] if you write code that updates the content of the current page, so that your changes are immediately visible. = Implementation = [@showproc refresh-this-page@]} 1115585259 #-------------------------------------------------- # Release Notes page {Release Notes} {= Notebook [@version@] Release Notes = Start Notebook and select "Topics" from the "Help" menu for documentation on how to use Notebook. The Notebook home page is at http://notebook.wjduquette.com This version of Notebook is fully usable; I use it myself, daily. However, it contains a number of experimental and undocumented features, and should be considered a work in progress. Some of the undocumented features might be changed, removed, or replaced in the next version. Meanwhile, though I'm not aware of any bugs it's likely some are lurking; and there are many features and enhancements I've not gotten to yet. Please don't be shy about telling me about problems you have or features you'd like to see. You can send me information by e-mailing me at will@wjduquette.com; or, better yet, post at them at the Notebook home page (see above). Also, you might want to join the Notebook Mailing List so you'll see the announcements of new releases. (Again, see the Notebook home page). == Installation == This version of Notebook is delivered as an executable for Windows systems, as a native executable for Mac OS X systems (10.3 or later) and as a Starkit for all other systems. To use Notebook on a Windows system, just execute notebook.exe. You might wish to associate it with the ".nbk" file type. To use Notebook on Mac OS X, just drag the Notebook application to your application folder. For other systems, you'll need to download "notebook.kit" and the TclKit runtime for your platform from http://www.equi4.com/pub/tk/8.4.9. Put the TclKit runtime on your path, and mark notebook.kit executable. If you have any questions, bug reports, suggestions, or comments, feel free to contact me, Will Duquette, at will@wjduquette.com, or post them at the Notebook Wiki, http://notebook.wjduquette.com. == Changes in Version 2.1.3 == * MacOSX: New application and document icons. Thanks to Kevin Walzer for pointing the way! * New feature: the [Index Sidebar]. The page index and search results are now shown in a sidebar on the right hand side of the window. ** The page index, the search box, and the search results are now available all of the time, even while editing pages. ** The Search and Recent Changes pages are no longer required. They will no longer be included in new notebooks, and may safely be deleted from old notebooks. Note that if you use such a notebook file with an older version of Notebook, the Search and Recent Changes pages will be recreated automatically. ** The goto-index and goto-recent-changes [User Interface Actions] are now deprecated. ** You can now search just page titles, or (the default) both page titles and content. ** Presenting the search results in the Sidebar is '''much''' faster than the older method; hence, incremental search is now the default. ** The Next Page/Previous Page keys (Control-N, Control-P) now work with the Sidebar's list. You can now step through pages alphabetically or in time order from most recent to least recent, and you can step through all pages or the current search results. ** New [Sidebar Menu] * Reorganized the [Page Menu] for quicker access to the most common choices. * Keyboard access to the [Search Box]. ** The [find-string] action now works through the [Search Box]. * New menu item: '''Page / Delete Pages...''' ** This menu item will delete the set of pages selected in the [Index Sidebar] (first prompting for confirmation). * New [Miscellaneous Preferences]: ** The sidebar may be open or closed in new windows by default. ** Search may be incremental or non-incremental by default. ** Search may be by page title only or by both page title and content by default. * Notebook now scrolls large images much better than it used to. Thanks to Wayne Mogg for coming up with the fix! As a side-effect, the image "-padheight" option has been removed. * New Actions/Notebook Commands: ** delete-pages ** searchtext ** show-index ** show-recent ** sidebar ** sidebar-byname ** sidebar-bytime ** sidebar-close ** sidebar-open * Bug Fix: Excess whitespace is no longer removed in link and magic button text. * Bug Fix: Notebook's keyboard shortcuts now work properly whether CapsLock is enabled or not. * Bug Fix: "-" markup for explicit line breaks. I added this markup in V2.1.1, and then took it out again in V2.1.2 in favor of <br>. However, I only took out half of the code, so that "-" still caused a line/paragraph break, but also appeared in the output. Enough people have spoken in favor of "-", though, that I reinstated it rather than removing it completely. * Bug Fix: When invoked from the command line, Notebook can now open multiple notebooks at the same time, as it is suppose to do. * Bug Fix: Notebook's fonts are oddly sized on some systems. You can now fix this by adjusting the "Tk Scaling Factor" on the [Scaling Preferences] tab of the [User Preferences] window. * Newly Deprecated: ** goto-index ** goto-recent-changes * The implementation of browser-specific Notebook Commands has been extensively revised. The new code is simpler, shorter, and should be easier to maintain; it's also the first step toward securing the User Code interpreter such that you can load Notebooks from unknown sources without worrying about what their User Code might do to your system. ** As a result, the "browser" Notebook Command is no longer needed. Because it does represent a security hole, and should never have been used directly by User Code anyway, it has been deleted rather than deprecated. If you were using "browser" directly for some reason, contact me and I'll see if I can provide an alternate mechanism. * The following Notebook commands were deprecated in Notebook 2.0.1 and have now been deleted from the application ** backpage ** editpage ** editnewpage ** includecode ** message ** renamepage ** showhelp ** shownext ** showpage ** showprev == Changes in Version 2.1.2 == * New Feature: Inline Images! Include images in your Notebook pages using the new markup: : &lb;!image path/to/file ?options...?!&rb; By default, Notebook understands only GIF images; with the optional [TkImg Extension] you also get BMP, JPEG, PNG, and TIFF files. (See the on-line help for more information about getting the [TkImg Extension].) Note that the Mac OS X version of Notebook already includes the [TkImg Extension]. * New Notebook Command: html. Allows you to control how Notebook exports HTML; in particular, allows you to define CSS (Cascading Style Sheet) styles. '''Note:''' this command is experimental; it is likely to change in the next version. It's not documented, but you can take a look at the [User Code] page of this on-line help for an example. * New Markup: <br> for explicit line breaks. The "-" markup I introduced in 2.1.1 has been removed; I can add it back in if folks like it. * New Markup: #rem directive. "rem" stands for "remark"; #rem directives are used to add comments to Notebook pages. #rem directives are not displayed or exported (unless all directives are displayed). * Bug fix: Notebook export to HTML no longer fails if two Notebook pages clash. * Bug fix: #meta directives were displayed as preformatted text in pages converted to HTML or MediaWiki markup. * Bug fix: MediaWiki export no longer misformats bulleted paragraphs. * Bug fix: Notebooks created without the Tour are now loaded successfully. * Bug fix: Explicit line breaks are now formatted properly on HTML export -- provided you use the new
markup instead of the "-" markup. * Bug fix: Selection of specially formatted text (e.g., #pre and #Tcl) is now visible. (Thanks to Vsu for pointing out the fix!) * Bug fix: In HTML export, headers now close indentation properly. * Bug fix: In HTML export, "<", ">", and "&" are now escaped properly in headers. * Bug fix: Links to non-existent pages are now highlighted when the Notebook is exported to HTML. == Changes in Version 2.1.1 == * New splash screen. The splash screen image was donated by Tomek Wojtowicz. * The on-line help now contains documentation for many changes made but not documented in 2.1.0. The relevant changes are listed under "Changes in Version 2.1.0" and are marked "Documented in 2.1.1". * New Feature: Export the entire notebook to HTML! The output is still rather basic, but it's a start. There are two new menu items: ** File/Export/As Single HTML File... ** File/Export/As Set of HTML Files... * The [User Code] page in the on-line help shows how to use the #Tcl/#unTcl directives to better document your Tcl code. * The Preferences dialog is now a normal toplevel window instead of a dialog. * Added "User Interface Actions" to the Help menu. * New Preference: Create new pages silently on link click. Normally, if you click on a link to a page that doesn't exist then Notebook will ask you if want to create it. If you check this box on the Miscellaneous tab of the Preferences window, Notebook will take you straight to the page editor instead. * New Feature: the status line's prompt now has a yellow background when it's waiting for you to answer a question or enter some input; this should make it easier for new users to spot. * New Preference: A long time ago, I made Notebook default to putting the cursor at the end of the page when you edit a page, because I was tired of moving the cursor there manually. Since then, I've gotten tired of moving the cursor to the beginning of the page manually. So I've changed the behavior to default to leaving the cursor at the beginning of the edited page. If you prefer the old behavior, there's a new option on the Miscellaneous tab of the Preferences window. * New Preferences: you can now specify foreground and background colors for preformatted text and Tcl code on the Colors tab of the Preferences window. * New Preference: you can turn display of "#" directives on and off. It is now off by default. * New Feature: Whenever search text is entered in the search entry field at the top of the page browser, any matching text in the browsed page will be highlighted. You may select the highlight colors you prefer on the Colors tab of the Preferences window. * New Markup: Explicit line breaks. If a line begins with "-", Notebook will always cause it to begin on a new line. The "-" and any subsequent whitespace are not displayed. * New Markup: Multi-level section headers. Notebook now allows three levels of header in a page: = Level 1 = == Level 2 == === Level 3 === : The first "=" character must be at the beginning of the line, and the header text must be separated from the "=" characters by at least one space. The final "=" must be the last thing on the line. If any of these constraints are not met, the header will be formatted as normal text, "=" characters and all. * New Markup: Wiki-like markup for bold and italic text: ''Italic'' '''Bold''' '''''Bold and Italic''''' * New Preference: Fonts for header levels 1, 2, and 3. Note that the in-line header markup, "<h>...</h>", is displayed in the level 3 header font. : If you've used prior versions of Notebook, all three header fonts will be set to the single header font you'd chosen previously. Use the Preferences window to select the specific fonts you'd like. * New Export Format: MediaWiki Markup. * New Notebook Commands: ** [codeget] ** [copy-page-as] ** [copy-this-page-as] ** [export-page-as] ** [export-this-page-as] ** [help-on-actions] * New User Interface Actions: ** [help-on-actions] ** [copy-page-as-mediawiki] ** [copy-this-page-as-mediawiki] ** [export-page-as-mediawiki] ** [export-this-page-as-mediawiki] ** [export-notebook-as-html-file] ** [export-notebook-as-html-set] * Updated Command: [current] ** The [current] command now allows embedded macros to know the page in which they are embedded, as well as the page in which they will be displayed. This is useful when writing code that builds up a page (like a Daily Log) from other pages. * Bug Fix: On OS X with Tcl/Tk Aqua, having a tooltip pop up for a toolbar button should no longer cause the Notebook window to lose focus. == Changes in Version 2.1.0 == * New Markup: You can have a page link whose link text differs from the page name. For example, you can link to your "Home" page as "My Home Page" using the following markup: [My Home Page|Home] * Support for international fonts. This version of Notebook includes all of Tcl's Unicode encodings, and should therefore support a variety of character sets, including Chinese. * New Feature: Magic/Load This Page will load the Tcl code from the current page even if you're currently editing the page. In this case it will save your edits before loading the the code; you'll remain in the editor. Documented in 2.1.1 * New Feature: Notebook now supports the #unpre directive, which allows multiple #pre/#unpre blocks of preformatted text on a page. * New Feature: Notebook now supports the #unTcl directive. #Tcl/#unTcl work like #pre and #unpre, but bracket Tcl code instead instead of preformatted text. User Code pages can now have multiple blocks of Tcl code interspersed with normal prose. * New Feature: Edit/Copy Page submenu. The items on this menu copy a page's content to the clipboard as plain formatted text, raw markup, markup with macros expanded, HTML body text, or as a complete HTML page. Documented in 2.1.1 * New Feature: Page/Export submenu. The items on this menu export a page's content to a text file as plain formatted text, raw markup, markup with macros expanded, HTML body text, or as a complete HTML page. Documented in 2.1.1 * New Markup: <html>...</html> Documented in 2.1.1 ** Use these tags within a paragraph to mark text that should be exported to an HTML page "as is", e.g., text that already contains HTML markup. * New Markup: #meta directive Documented in 2.1.1 * New Markup: #data .. #undata Documented in 2.1.1 ** These directives are used to bracket arbitrary textual data just as #pre and #unpre bracket preformatted text. The #data directive includes the data type name, which will allow for additional processing. ** The contents of a data block are (at present) displayed as preformatted text. ** The only "data type" recognized by Notebook in any way at this time is "html"; on export to HTML, the contents of an "html" data block is exported as is. * New User Interface Actions. Documented in 2.1.1 ** [copy-page-as-plain-text] ** [copy-page-as-raw-markup] ** [copy-page-as-expanded-markup] ** [copy-page-as-html-page] ** [copy-page-as-html-text] ** [copy-this-page-as-plain-text] ** [copy-this-page-as-raw-markup] ** [copy-this-page-as-expanded-markup] ** [copy-this-page-as-html-page] ** [copy-this-page-as-html-text] ** [export-page-as-plain-text] ** [export-page-as-raw-markup] ** [export-page-as-expanded-markup] ** [export-page-as-html-page] ** [export-page-as-html-text] ** [export-this-page-as-plain-text] ** [export-this-page-as-raw-markup] ** [export-this-page-as-expanded-markup] ** [export-this-page-as-html-page] ** [export-this-page-as-html-text] * New Notebook Commands. Documented in V2.1.1 ** [exportformat] ** [formatas] ** [savefile] ** [getsavefile] ** [parse] * Bug fix: Selecting File/Close Window from the Message Log window now closes the window as expected. * Bug fix: Selecting "Cancel" from the Open Notebook or New Notebook dialogs no longer causes Notebook to halt. (This only happened if open-notebook or new-notebook were invoked from the Welcome window.) * Bug fix: If load-page finds an error in the loaded page, the error is now written to the status line and the Message Log window. * Bug fix: You can now rename page "Fred" to "x-Fred" without error, and you can now delete "Fred" without deleting "x-Fred" as well. * Bug fix: Pressing the "Save and Continue Editing" button in the Page Editor no longer causes other open Notebook browsers to pop up or take the focus unexpectedly. * Bug fix: Previously, if you edited a page and then immediately tried to find a string on that page, the search always failed because the cursor was at the bottom of the page. In this case, Notebook now starts searching from the top of the page, as you'd expect. * Bug fix: In the page browser, the behavior of the Home and End keys was erratic. Home now scrolls to the top of the page and End to bottom, as expected. * Bug fix: Previously, pasting text into the page editor could leave the insertion point off-screen. The page editor now scrolls as necessary after each paste. } 1117486303 #-------------------------------------------------- # rename-page page rename-page {#rem command #rem action = Syntax = rename-page ?''oldname''? ?''newname''? = Description = This command can be invoked as a [User Interface Action]. Renames the page named oldName to newName. In addition, it updates all links to oldName in your Notebook to refer to newName instead, and saves all changes. If oldName or newName are not specified, Notebook prompts the user to enter them. Contrast [rename-page] with [pagerename], which neither prompts the user nor saves the changes. = Examples = The following call, used as a [magic button] or on your [usermenu], will rename a page, prompting the user to enter both the old and new names: #pre rename-page #unpre The following call will prompt the user to enter a new name for the "Badly Named Page": #pre rename-page "Badly Named Page" #unpre Finally, the following call will simply give the "Badly Named Page" a better name: #pre rename-page "Badly Named Page" "A Better Name" #unpre = Implementation = [@showproc rename-page@]} 1115585287 #-------------------------------------------------- # rename-this-page page rename-this-page {#rem command #rem action = Syntax = rename-this-page ?''newname''? = Description = Prompts the user for a new name for the current page, and then renames the page and updates all links to it. This action is equivalent to the Page/Rename This Page menu item. = Examples = #pre rename-this-page "The New Name" #unpre = Implementation = [@showproc rename-this-page@]} 1115585308 #-------------------------------------------------- # replace-string page replace-string {#rem command #rem action = Syntax = replace-string = Description = While editing, replaces for all occurrences of a string between the insertion point and the end of the page with some other string. Prompts the user to enter both strings. This action is equivalent to the Edit/Replace menu item. = Examples = #pre replace-string #unpre = Implementation = [@showproc replace-string@]} 1115585325 #-------------------------------------------------- # request page request {#rem command = Syntax = request ''options...'' = Description = The [request] command allows your code to prompt the user for information. It's a powerful, complex command; [askfor] is simpler to use and might meet your needs. [request] differs from [askfor] in the following ways: * You can specify more than one prompt; the user will be asked for each in turn. * For each prompt, you can specify a default response and a list of valid responses. * Your request can be synchronous or asynchronous. "Synchronous" means that the user must respond to all of the responses (or press Escape to cancel the request) before they can interact with the rest of the Notebook application. "Asynchronous" means that they can interact with Notebook (e.g., they can go to a different page) and then go back to entering a response. By comparison, [askfor] is always synchronous. * By default the request is synchronous; [request] will return a list of the responses. If the user presses Escape to cancel the request, the entire user-defined [notebook command] is cancelled. * The request becomes asynchronous if the -command option is given; in this case, [request] returns nothing. The prompts and associated data are specified by a list of options. The options can be specified in one of two formats: : request option value option value... or : request {option value option value...} The latter form makes it easy to create a list of options and pass it to [request]: #pre set options {} if {$author eq ""} { lappend options -prompt "Author" } if {$title eq ""} { lappend options -prompt "Title" } set result [request $options] #unpre = Options = [request] accepts the following options: -prompt prompt : Defines a prompt. The user will be prompted to enter a response using the specified prompt. If multiple -prompt options are specified, the user will be prompted for each in the order of appearance. -enum responses : Specifies a list of valid responses for the previous -prompt. If the user presses the Tab key, Notebook will attempt to complete any partial response they've entered by matching it against the responses. -strict 0|1 : This option is used with -enum. If -strict 1, then the only valid responses are those specified using -enum, and the user will not be allowed to enter anything else. If -strict 0 (the default) then the user can enter anything they like. [delete-page] uses -strict 1 when prompting a user to enter a page name, because you can't delete a non-existent page; [edit-page] uses -strict 0 because it can be used to create new pages. -default value : Specifies a default value for the previous -prompt. If a default value is given, it will be highlighted in the status line when the user is prompted. The user can accept the default by pressing Enter, or just start typing in their own response, in which case the default disappears. -command command : By default, [request] prompts the user synchronously. If this option appears, command should be a Tcl command which expects as many additional arguments as there are -prompt options. Notebook will prompt the user for the options asynchronously; when all have been entered, Notebook will append the responses to the command and call it. = Examples = The following calls to [askfor] and [request] are equivalent. Note that [askfor] returns the response; [request] returns a list in which the response is the first element: #pre set response [askfor "My Prompt"] set response [lindex [request -prompt "My Prompt"] 0] #unpre The following code prompts synchronously for two values: #pre set responses [request -prompt "First" -prompt "Second"] set first [lindex $responses 0] set second [lindex $responses 1] #unpre The following code prompts for a page name; the page must exist, and the default value is the current page: #pre set responses [request -prompt "Page" -enum [pages] -strict 1 -default [current]] set name [lindex $responses 0] #unpre The following code prompts for a page name asynchronously; the user's response will be passed to a command called DoSomething: #pre proc DoSomething {name} { ... } request -command DoSomething -prompt "Page" -enum [pages] -strict 1 -default [current] #unpre = Implementation = [@showproc request@]} 1115585352 #-------------------------------------------------- # request-action page request-action {#rem command #rem action = Syntax = request-action = Description = Prompts the user to enter the name of a [User Interface Action], and then invokes the chosen action. This action is equivalent to the File/Invoke Action menu item. = Examples = #pre request-action #unpre = Implementation = [@showproc request-action@]} 1115585367 #-------------------------------------------------- # require page require {#rem command = Syntax = [@signature require@] = Description = When writing procs in your [User Code Page], use [require] to check conditions that must be true for your procs to execute correctly. [require] evaluates the expression; if the expression is true then execution continues normally. Otherwise, the message will be written to the status line and to the [Message Log]. [require] is similar to [assert], except that [require] failures are less severe. If an [assert] fails, the presumption is that the programmer made a mistake. If a [require] fails, the presumption is that the user asked for something that can't currently be done. For example, [delete-page] is a high-level command for deleting a page. If the user tries to delete a page that doesn't exist, that's a [require] failure, and Notebook simply informs the user that the page doesn't exist. [pagedelete], on the other hand, is a low-level command available only to your User Code. If you use [pagedelete] to delete a non-existent page, that's a programming error; Notebook will write a complete stack trace to the [Message Log]. = Examples = Suppose you were implementing your own version of the [insert-page] command--you could implement it like this: #pre proc insert-page {name} { require {[pageexists $name]} "There's no page called '$name'!" insert [pageget $name] } #unpre [pageget] is a low-level command, and will throw an error and stack-trace if the named page doesn't exist. The call to [require] ensures that the user will get a nice error message instead. Note also that you can only insert something into the editor if you're editing a page--but you don't need to check this because the [insert] command checks it for you. = Implementation = [@showproc require@]} 1114962080 #-------------------------------------------------- # save-and-continue page save-and-continue {#rem command #rem action = Syntax = save-and-continue = Description = While editing, saves the current contents of the page to disk but allows you to go on editing. This action is equivalent to the "floppy disk" toolbar button. = Examples = #pre save-and-continue #unpre = Implementation = [@showproc save-and-continue@]} 1115585382 #-------------------------------------------------- # save-edits page save-edits {#rem command #rem action = Syntax = signature save-edits = Description = While editing, saves your edits and returns to the browser. This action is equivalent to pressing the "checkmark" button on the toolbar, or pressing the Ctrl+S key. = Examples = #pre save-edits #unpre = Implementation = [@showproc save-edits@]} 1115585391 #-------------------------------------------------- # savefile page savefile {#rem command = Syntax = savefile ''filename text'' = Description = Saves the specified text to the named file, overwriting any existing file with that name. = Examples = #pre savefile myfile.html [formatas html-page "My Page"] #unpre = Implementation = [@showproc savefile@]} 1115585412 #-------------------------------------------------- # Scaling Preferences page {Scaling Preferences} {The '''Scaling''' tab of the [User Preferences] window allows you to adjust the value of the Tk Scaling Factor. You can enter a new value and press "Apply"; the new value will take effect the next time you restart Notebook. Press "Restore Default Value" to restore Notebook's default scaling factor for your computer. = The Tk Scaling Factor = In order to render your font choices properly (among other things), Notebook needs to know the physical size of the pixels on your computer screen. The value it uses to do this is called the Tk Scaling Factor, and it's measured in pixels-per-point. One point is equal to 1/72 of an inch, so the Tk Scaling Factor can also be thought of as the resolution of your screen in pixels-per-inch (PPI) divided by 72.0. Notebook does the best it can to determine the Tk Scaling Factor on its own, but on some systems it's unable to get good data for the physical dimensions of your computer screen. If this happens you'll know because Notebook will display its fonts at sizes which are out of proportion with the other applications you use. '''If you're happy with the size of your fonts, don't adjust the Tk Scaling Factor.''' But if the size is off from what it should be, read on. = Determining the correct scaling factor = There are two methods for determining the correct Tk Scaling Factor. == Method 1: Measure your screen. == Use an ordinary ruler to measure the width of your screen in inches. The width of your screen in pixels is displayed on the '''Scaling''' tab of the [User Preferences] window. Then compute pixels factor = ------------- inches*72.0 Alternatively, if you know the resolution of your screen in pixels-per-inch, just divide that by 72.0. Enter the result in the Tk Scaling field, and press Apply. You'll need to restart Notebook to see the difference. == Method 2: Font Comparison == On some systems, Method 1 will fail--because the system doesn't try to display fonts at their full size. On my Apple PowerBook, for example, Method 1 gives me a scaling factor of about 1.4. If I use that value, though, Notebook displays fonts about 40% larger than other applications do. The default scaling factor is about 0.99, which turns out to be just right. Laptop screens are small, and your eyes tend to be closer to them; text is legible at smaller sizes. I suspect Apple did things this way so that you can get more text on the screen. If Method 1 fails then bring up another application--a word processor, say--alongside Notebook, and have it display a known font--say, Arial 20pt. Set Notebook to use the same font as its "Title Font". Then adjust the scaling factor until Notebook displays the font at the same size as the other application. Note that you'll need to restart Notebook in order to see the effects of changing the scaling factor.} 1117471465 #-------------------------------------------------- # Search page Search {[@searchIndex@]} 1026257614 #-------------------------------------------------- # Search Box page {Search Box} {The Search Box appears in the middle of the [page browser] toolbar; you can see it just above this page. It's a long rectangle; at the left is an icon of a magnifying glass over a piece of paper and a "down arrow" icon; at the right (if there's any text in the Search Box) is an "x" in a circle. You can find out which pages contain any desired string in their names or content by typing it into the Search Box. The found pages will be listed in the [Index Sidebar]; double-click on any page to browse it. '''Note:''' Notebook searches the raw markup of each page, just as you'd see it in the [page editor]. You can activate the Search Box several ways--you can click on the page's title (and thereby search for occurrences of the title on other pages); you can click in the Search Box and start typing; or you can select Edit / Find (Command-F on MacOSX, Control-F on other systems) and start typing. Whenever you view or edit a page, any text that matches the text in the Search Box will be highlighted. You can select the search highlight colors in the [Color preferences] tab of the [User Preferences] window. If you enter search text into the Search Box while editing a page, pressing Return in the Search Box will take the focus back to the [page editor] and move the insertion cursor to the next occurrence of the search text. Thereafter, Edit / Find Again will step through subsequent occurrences. To make the highlights go away, click the circled "x" at the right of the Search Box or press Escape. This will clear the search text and make the highlights go away; the [Index Sidebar] will then list all pages in the notebook. = Search Options = Clicking on the black "down arrow" icon pops up the Search Options menu. Incremental Search vs. Non-Incremental Search: By default, Notebook updates the search results with each character you enter in the Search Box. This can be slow for large notebooks. If you select Non-Incremental Search, the search results will only be updated when you press Enter in the Search Box. If you prefer Non-Incremental Search, you can disable Incremental Search permanently on the [Miscellaneous Preferences] tab of the [User Preferences] window. It can then be re-enabled temporarily via this menu. Title and Contents vs. Title Only: By default, Notebook searches both the title and contents of each page in your notebook. You can limit the search to the page titles by selecting Title Only. If you prefer to search only the page titles, you can disable content search permanently on the [Miscellaneous Preferences] tab of the [User Preferences] window. It can then be re-enabled temporarily via this menu.} 1116796221 #-------------------------------------------------- # searchIndex page searchIndex {#rem command = Syntax = [@signature searchIndex@] = Description = This [embedded macro] expands into a formatted alphabetic list of pages whose titles or contents contain the search text from the Search field (see [page browser]). = Examples = The standard [Search] page consists of the following embedded macro: #pre [@lb@]searchIndex[@rb@] #unpre There's not much other reason to use [searchIndex]. = Implementation = [@showproc searchIndex@]} 1114962087 #-------------------------------------------------- # searchtext page searchtext {#rem command = Syntax = searchtext = Description = Returns the text string currently shown in the [Search Box], or the empty string if the [Search Box] is empty. = Examples = #pre The search text is '[@lb@]searchtext[@rb@]' #unpre = Implementation = [@showproc searchtext@]} 1115586290 #-------------------------------------------------- # Section Headers page {Section Headers} {It's often desirable to break a long page into sections with section headers. Notebook gives you three levels of section header: = A Level 1 Header = == A Level 2 Header == === A Level 3 Header === You can select any [any font you like|Font Preferences] for each kind of header. The markup for these three kinds of header looks like this: #pre = A Level 1 Header = == A Level 2 Header == === A Level 3 Header === #unpre There are some important rules: * The "=" must be the first character on the line. * There must be no text (not even whitespace) following the final "=" on the line. * There must be at least one space character between the "=" characters and the actual text of the header. If any of these rules are broken, the line will be formatted as normal text. If you want blank lines before and after the header, you'll need to enter them yourself. = By The Way = If you find yourself wanting to divide a page into sections, that may be a sign that you should divide the page into several linked pages; see [Creating links to other pages] for more.} 1113332992 #-------------------------------------------------- # show-index page show-index {#rem command #rem action = Syntax = show-index = Description = This command can be invoked as a [User Interface Action]. Opens the [Index Sidebar] if it is closed, and fills it with an alphabetical index of all of the pages in the notebook. In addition, it clears any text in the [Search Box]. = Examples = #pre show-index #unpre = Implementation = [@showproc show-index@]} 1115585424 #-------------------------------------------------- # show-recent page show-recent {#rem command #rem action = Syntax = show-recent = Description = This command can be invoked as a [User Interface Action]. Opens the [Index Sidebar] if it is closed, and fills it with an time-sorted index of all of the pages in the notebook. The pages are listed from the mostly recently edited page to the least recently edited. In addition, it clears any text in the [Search Box]. = Examples = #pre show-recent #unpre = Implementation = [@showproc show-recent@]} 1115585434 #-------------------------------------------------- # show-version page show-version {#rem command #rem action = Syntax = show-version = Description = Shows the current Notebook version on the status line. = Examples = #pre show-version #unpre = Implementation = [@showproc show-version@]} 1115585445 #-------------------------------------------------- # showsearch page showsearch {#rem command = Syntax = showsearch ''searchtext'' = Description = Enters the ''searchtext'' in the [Search Box], and displays the results in the [Index Sidebar]. = Examples = The following command does a search for the word "Cheese": #pre showsearch "Cheese" #unpre = Implementation = [@showproc showsearch@]} 1115585525 #-------------------------------------------------- # sidebar page sidebar {#rem command = Syntax = sidebar pages
sidebar selection = Description = The sidebar is used to access the pages listed in the [Index Sidebar]. The form sidebar pages returns the names of all the pages currently listed in the sidebar; the form sidebar selection returns the names of all the pages currently selected in the sidebar. = Examples = There are an endless number of possible uses for this information; here's a [User Code] function that formats all selected pages as plain text, and returns the result: #pre proc formatselected {} { set result {} foreach name [sidebar selection] { append result [formatas plain $name] } return $result } #unpre = Implementation = [@showproc sidebar@]} 1115586147 #-------------------------------------------------- # Sidebar Menu page {Sidebar Menu} {The Sidebar menu is used to manipulate the [Index Sidebar], which displays a list of some or all of the pages in the notebook. The menu has the following items; the related [User Interface Action] is listed after each in parentheses. * Sidebar / Show Index ([show-index])
Opens the [Index Sidebar] if it is closed, and fills it with an alphabetical index of all of the pages in the notebook. In addition, it clears any text in the [Search Box]. * Sidebar / Show Recent Changes ([show-recent])
Opens the [Index Sidebar] if it is closed, and fills it with an time-sorted index of all of the pages in the notebook. The pages are listed from the mostly recently edited page to the least recently edited. In addition, it clears any text in the [Search Box]. * Sidebar / Close Sidebar ([sidebar-close])
Closes the [Index Sidebar] if it's open. * Sidebar / Sort by Name ([sidebar-byname])
Sorts the page names listed in the [Index Sidebar] alphabetically. * Sidebar / Sort by Time ([sidebar-bytime])
Sorts the page names listed in the [Index Sidebar] by how recently the pages have been edited, from most recently to least recently.} 1114966676 #-------------------------------------------------- # sidebar-byname page sidebar-byname {#rem command #rem action = Syntax = sidebar-byname = Description = This command may also be invoked as a [User Interface Action]. Sorts the pages listed in the [Index Sidebar] alphabetically. As such, it's equivalent to selecting the Sort by Name item from the [Sidebar Menu], or clicking the "A to Z" icon on the [Index Sidebar] itself. = Examples = #pre sidebar-byname #unpre = Implementation = [@showproc sidebar-byname@]} 1115585564 #-------------------------------------------------- # sidebar-bytime page sidebar-bytime {#rem command #rem action = Syntax = sidebar-bytime = Description = This command may also be invoked as a [User Interface Action]. Sorts the pages listed in the [Index Sidebar] by how recently they've been edited, from most recently to least recently. As such, it's equivalent to selecting the Sort by Time item from the [Sidebar Menu], or clicking the "clock" icon on the [Index Sidebar] itself. = Examples = #pre sidebar-bytime #unpre = Implementation = [@showproc sidebar-bytime@]} 1115585573 #-------------------------------------------------- # sidebar-close page sidebar-close {#rem command #rem action = Syntax = sidebar-close = Description = This command may also be invoked as a [User Interface Action]. Closes the [Index Sidebar] if it's currently open. = Examples = #pre sidebar-close #unpre = Implementation = [@showproc sidebar-close@]} 1115585582 #-------------------------------------------------- # sidebar-open page sidebar-open {#rem command #rem action = Syntax = sidebar-open = Description = This command may also be invoked as a [User Interface Action]. Opens the [Index Sidebar] if it's currently closed. The content of the sidebar is unchanged. = Examples = #pre sidebar-open #unpre = Implementation = [@showproc sidebar-open@]} 1115585592 #-------------------------------------------------- # Special Characters page {Special Characters} {The characters "&lb;", "&rb;", "<", and ">" are used as markup to enable [text styles], [creating links to other pages], [embedded macro]s, and [magic button]s. What do you do if you want to put them in a page and have them display as is? You have several choices. * Use [preformatted text]. Except for [embedded macro]s, all of the special markup is displayed as is in [preformatted text]. * The "<" and ">" characters are only special in the "<b>" tag and its companions; see [Text Styles] and [Section Headers]. Otherwise, you can use them freely. * Or, you can use one of the following "escape sequences", which will be replaced by the character you chose: Character Escape Sequence Mnemonic --------- --------------- ----------------- [ &lb; "Left Bracket" ] &rb; "Right Bracket" < < "Less Than" > > "Greater Than" : Escape sequences work everywhere but in [directives] and [preformatted text].} 1072223045 #-------------------------------------------------- # super page super {#rem command = Syntax = super ... = Description = The super command is an alias for uplevel #0 in the application's main interpreter; it allows your code to touch the application itself. You probably shouldn't use super unless the preceding explanation was sufficient to tell you what it's for. Used carelessly, super can damage the integrity of the application--and possibly cause you to lose your data. = Examples = I don't think so. = Implementation = [@showproc super@]} 1114962095 #-------------------------------------------------- # Tcl/Tk Preferences page {Tcl/Tk Preferences} {The Tcl/Tk tab of the [User Preferences] window allows you to configure Notebook's Tcl/Tk interpreter. '''Extensions Directory:''' If your [User Code Page] draws on any Tcl/Tk extension packages, you can enter the absolute path of the directory that contains them here. After you restart, your [User Code] should be able to "require" the packages. See also [TkImg Extension].} 1114385601 #-------------------------------------------------- # template page template {#rem command = Syntax = template name arglist ?initbody? template = Description = The [template] command defines a new command used to format text. The new command has a name and arglist just like a normal Tcl "proc". The template is a text string that can contain embedded commands and variables. When you call the template command, the variables and commands are substituted into the text string, which is then returned. If given, the optional initbody is executed before the substitution is done; it will usually define new variables for use in the template If the first non-blank line of the template is "|<--", then the vertical bar character specifies the left margin; see [tsubst] for more. Use templates as [embedded macro]s. = Examples = The following template greets the user and tells them the name of the current page: #pre template greeting {first last} { |<-- Hello, $first $last! You're looking at a page called '[Current]'! } #unpre The "|<--" is very important; it indicates that all of the whitespace to the left of the "|<--" should be thrown away. That means that when this macro is expanded, the lines of text will begin in the first column, and will be formatted normally. If "|<--" was omitted, the returned text would be assumed to be preformatted. Here's what this template looks like as an embedded macro: #pre [@lb@]greeting John Doe[@rb@] #unpre = Implementation = [@showproc template@]} 1114962110 #-------------------------------------------------- # Text Styles page {Text Styles} {You can add boldface, italics, or monospace text, or any combination of the three to any text you like; you can also add Header Text and very small text. = Bold And Italic Text = Text can be '''bolded''' and ''italicized'' using either a traditional wiki-like notation or an HTML-like notation: #pre This is '''bold''' and so is this. #unpre This is '''bold''' and so is this. #pre This is ''italicized'' and so is this. #unpre This is ''italicized'' and so is this. Boldface and italics can be combined, using either style: #pre Wiki-style: '''''bold and italics''''' #unpre Wiki-style: '''''bold and italics''''' #pre HTML-style: bold and italics #unpre HTML-style: bold and italics = Other Text Styles = The other text styles have only an HTML-like syntax: * <m>...</m> -- Display the enclosed text in monospace. * <h>...</h> -- Display the enclosed text as an inline header. * <s>...</s> -- Display the enclosed text so that it doesn't stand out. * <x>...</x> -- Display the enclosed text with a line through it. For example, if you typed in this: #pre : Some words are bold and others are italicized, and some are both, while others are struck out. Note that Inline Header text and small text cannot be combined with the other styles. strikeout can be combined with anything #unpre you'd get : Some words are bold and others are italicized, and some are both, while others are struck out. Note that Inline Header text and small text cannot be combined with the other styles. strikeout can be combined with anything If you leave out the closing tags, the style will last only to the end of the paragraph.} 1114360808 #-------------------------------------------------- # The Tcl Language page {The Tcl Language} {Tcl is a simple scripting language; in fact, it's the language in which Notebook is written. You can use Tcl to extend Notebook however you like, by [defining new commands] on your "User Code" page. For more about Tcl, go to http://www.tcl.tk. You can also find out more about Tcl at the Tcler's Wiki, http://wiki.tcl.tk, and the Usenet newsgroup comp.lang.tcl.} 1072224096 #-------------------------------------------------- # TkImg Extension page {TkImg Extension} {The TkImg extension is a binary extension to Tcl/Tk that allows Tcl/Tk applications to read and write a variety of image formats. If you're using Notebook on Mac OS X, then TkImg was included with the executable. Otherwise, you'll have to get your own copy. You need at least TkImg 1.3. = TkImg on SourceForge = One way to get TkImg is to download the source from SourceForge and build it yourself. The address is : http://sourceforge.net/projects/tkimg/ = ActiveTcl = Alternatively, if you download ActiveTcl for your platform you'll TkImg along with it. ActiveTcl is a "batteries included" distribution of the Tcl/Tk programming language; that means it comes with lots of extra packages, like TkImg. You can get ActiveTcl from : http://www.activestate.com = Making TkImg Accessible to Notebook = Once you've got TkImg either built or installed with ActiveTcl, the next step is to find it on your disk. If you built it, of course, you can put it whereever you like. If you installed ActiveTcl, then there will be a "lib" directory somewhere which contains subdirectories for all of the packages. One of these subdirectories will be called "Img"; that's the one you want. Now, invoke the [User Preferences] window; there's a new tab labeled "Tcl/Tk". On that tab is an entry labeled "Extensions Directory:". Put the name of the directory containing the TkImg library in that entry, press "Apply", and then shutdown and restart Notebook. Once you've restarted Notebook, pop up the Message Log window; there will be an entry saying whether Notebook was able to load TkImg or not.} 1114385446 #-------------------------------------------------- # tsubst page tsubst {#rem command = Syntax = [@signature tsubst@] = Description = [tsubst] is a modified version of the standard Tcl "subst" command. The template is a string containing (possibly) variable references, command references, and backslashes; [tsubst] substitutes the value of the variables and commands into the string in place of the references, and removes the backslashes, and returns the result. If the first non-blank line of the template is the string "|<--", then the "|" character specifies the left margin of the template; all whitespace characters to the left of "|<--" will be thrown away. [tsubst] is a convenient way to format a large block of text. If you need to use [tsubst] with the same template in several places, consider using the [template] command instead. = Examples = The code #pre set name "John Doe" tsubst { |<-- Hello, $name! } #unpre returns the string "Hello, John Doe!" = Implementation = [@showproc tsubst@]} 1114962114 #-------------------------------------------------- # undo-change page undo-change {#rem command #rem action = Syntax = undo-change = Description = This command can be invoked as a [User Interface Action]. While editing, calling [undo-change] will undo the last set of edits; it's equivalent to selecting Edit/Undo from the application menu. = Examples = [undo-change] is mostly useful as an item on your [editmenu]. = Implementation = [@showproc undo-change@]} 1115585605 #-------------------------------------------------- # User Code page {User Code} {In a typical notebook, this page is used to customize the behavior or your notebook by defining new [Notebook Commands], [customizing the User Menu], and [customizing the Edit Menu]. In this Help notebook, it contains the Tcl code I use to maintain the Notebook on-line help. See [User Code Page] for more about the [User Code] page. If you're interested in teaching your Notebook to do magic, go ahead and read the rest of the page; it's well-documented. If you want to use any of the new commands, you'll need to copy the Tcl code to your own [User Code] page. Note that each of the code blocks is bracketed by [#Tcl] and [#unTcl] directives; these indicate that the code is in fact Tcl code, and may be loaded and executed. = The Editor User Menu = The [editmenu] command defines the popup menu that appears when you right-click in the [Page Editor] window; see [Customizing the Edit Menu] for details. In this case, I use the Edit menu to insert two kinds of template text into new pages. The first, insert-manpage, inserts the skeleton of a [Notebook Command] page; the second, insert-menu-item, inserts a fragment of text documenting a menu item. Both of these commands are defined lower done on this page. #Tcl -- Edit Menu editmenu { "Template: Manpage" {insert-manpage} "Template: Menu Item" {insert-menu-item} } #unTcl = Indenting Blocks of Text = Given a block of text, the indent command indents the block by the specified amount of whitespace. Put another way, the value of spaces is prepended to each line of text in text. By default, that's one space character. #Tcl -- indent proc indent {text {spaces " "}} { join [split "$spaces[string trim $text]" "\n"] "\n$spaces" } #unTcl = Removing Unwanted Indentation = The indent adds a white-space string to the beginning of each line in a block of text; the following command does the opposite: it figures out how much the block of text as a whole has been indented, and removes the indent. #Tcl -- unmargin proc unmargin {text} { # FIRST, break the text into lines. set lines [split $text "\n"] # NEXT, skip any initial blank lines. while {[llength $lines] > 0} { set line [lindex $lines 0] if {[string trim $line] eq ""} { lshift lines } else { break } } # NEXT, for the remaining non-blank lines determine the length of the # minimum whitespace prefix. set min 100 foreach line $lines { if {[regexp {^(\s*)\S} $line dummy prefix]} { set len [string length $prefix] if {$len < $min} { set min $len } } } # NEXT, remove that much space from the block of text. set prefix [string repeat " " $min] regsub -all "\n$prefix" [string trim $text] "\n" text return $text } #unTcl = Formatting Tables of Links = The [Notebook Commands] page and the [User Interface Actions] page each contain a list of command names or action names formatted as a multi-column alphabetized table of links to the relevant help pages. Notebook has no table capability at present, but the following command cheats by taking advantage of the fact that command and action names are displayed in a monospace font. Given the names, it figures out how many columns will fit, and how wide each column should be, and pads each column with spaces so that the names all line up. #Tcl -- linktable proc linktable {names} { # FIRST, get the maximum name length. set max 0 foreach name $names { set len [string length $name] if {$len > $max} { set max $len } } # NEXT, add 2 for column breaks. incr max 2 # NEXT, compute the number of columns set ncols [expr {int(75/$max)}] # NEXT, format the table. set result ": " set col 0 set fmt "%-[expr {$max + 2}]s" foreach name $names { append result [format $fmt "\[$name\] "] incr col if {$col == $ncols} { append result "\n: " set col 0 } } append result "\n" return $result } #unTcl = Auto-Generating Tables of Links = The following command generates a table of links by searching on a [#rem] keyword. #Tcl proc autolinktable {keyword} { linktable [pagesearch "#rem $keyword"] } #unTcl = Retrieving Command Signatures = The "signature" of a [Notebook Command] -- or any other kind of Tcl command, really, is a line of text that includes the command's name and the name of each argument. Each argument name is enclosed in question marks if the argument is optional. Every notebook command page in this help document includes the signature of the command. Keeping those signatures up to date as commands evolve is a nuisance--if you try to do it by hand. Instead, I use the signature [embedded macro]. Given a command name, signature returns the signature of the named command. signature takes two options: -argstext text : Use this option when the command has an "args" argument; the text is substituted in the signature for the word "args". -link flag : If flag is non-zero, the command name in the returned signature will be a link to the named command's page. signature is defined as follows: #Tcl -- signature proc signature {procname args} { set opt(-argstext) "" set opt(-link) 0 foreach {option value} $args { if {![info exists opt($option)]} { error "Unknown option $option" } set opt($option) $value } set argspec {} foreach arg [info args $procname] { if {$arg eq "args"} { if {$opt(-argstext) ne ""} { append argspec "?$opt(-argstext)? " } else { append argspec "?args...?" } } elseif {[info default $procname $arg defvalue]} { append argspec "?$arg? " } else { append argspec "$arg " } } if {$opt(-link)} { set procname "\[$procname\]" } return "$procname [string trim $argspec]" } #unTcl = Showing the Implementation of a Notebook Command = The showproc command is related to the signature command, but instead of retrieving the signature of a specified command, it returns a copy of the command's definition, that is, the command's code. This is not always possible; some standard [Notebook command]s are defined in such a way that their implementation isn't accessible. In that case, showproc returns the text "The code is unavailable". If desired, you can specify an indent string; it will be prepended to each line of the command definition. #Tcl -- showproc proc showproc {procname {indent " "}} { # FIRST, is this a proc? if {[info procs $procname] eq ""} { return "The code is unavailable." } # NEXT, format the argument list set argspec {} foreach arg [info args $procname] { if {[info default $procname $arg defvalue]} { lappend argspec [list $arg $defvalue] } else { lappend argspec $arg } } # NEXT, get the body, and strip off the extra whitespace at the # beginning of each line. set body [unmargin [info body $procname]] # NEXT, get the full proc definition, and indent it one space. set procdef "proc $procname {$argspec} {\n[indent $body { }]\n}" return "\n#pre\n$procdef\n#unpre\n" } #unTcl = Man Page Templates = In Unix parlance, a "man page" -- short for "manual page" -- is a single page that documents some program, command, function, file format, or what have you. Given that I'm a Unix programmer by trade, I tend to think of the Notebook page that documents each [Notebook command] as a man page. The following [template] defines the skeleton for a new man page. As you can see, this skeleton includes the signature and showproc [embedded macro]s defined above. The manpage [template] creates a man page skeleton; the insert-manpage command, defined below, actually inserts it into a page in the page editor. #Tcl -- manpage template manpage {command} { |<-- [mankeywords $command] = Syntax = \[\@signature $command@\] = Description = TBD. = Examples = #pre $command #unpre = Implementation = \[\@showproc $command\@\] } proc mankeywords {command} { # Split the result so that it doesn't match searches set result "#rem " append result "command" if {[string match "*-*" $command]} { append result "\n#rem " append result "action" } return $result } #unTcl The following command inserts a man page skeleton into the page currently being edited in the [Page Editor]. As you can see, it assumes that the page name, returned by "[current]", is the name of the command to document. #Tcl proc insert-manpage {} { insert [manpage [current]] } #unTcl = Inserting Menu Item Entries = In the help pages that document Notebook's various menus, there's a standard form for documenting each menu item. The menu item's name is show in bold, followed by the name of the associated [user interface action] in small type. The description begins on the next line, indented. The following command prompts for the menu item name and the action name, and inserts it all in the proper format. #Tcl -- insert-menu-item proc insert-menu-item {} { set item [askfor "Menu Item"] set action [askfor "Action"] insert [tsubst { |<-- * $item (\[$action\])
}] } #unTcl = HTML Style Sheet = We can use the html command to configure Notebook's HTML export features. In particular, we can include style-sheet information in the exported pages. (Alas, it doesn't affect pages exported just as html-text.) #Tcl html configure -css { h1 { color: yellow; background: #990000; margin-left: -4%; font-family: "Arial Rounded MT Bold" Helvetica Arial sans; } h2, h3, h4 { margin-left: -4%; font-family: "Arial Rounded MT Bold" Helvetica Arial sans; } hr { margin-left: -5%; margin-right: -5%; } body { margin-left: 5% ; margin-right: 5%; } pre { outline: thin dashed blue; padding-top: 2px; padding-bottom: 2px; padding-left: 4 px; background: #FFFF99; } } -nbtitle "Notebook [version]" #unTcl = Displaying Embedded Macro Brackets = The following macros are used to include the embedded macro brackets, &lb; and &rb;, in preformatted text. #Tcl proc lb {} {return "\[\@"} proc rb {} {return "\@\]"} #unTcl} 1114964633 #-------------------------------------------------- # User Code Page page {User Code Page} {Notebook is an extensible application--you can write code in the [the Tcl Language] to make it do new things. But where do you put this code? Every notebook includes a page called [User Code]; any Tcl code you put on this page is loaded automatically when your notebook is loaded into a browser. (If you click on the [User Code] link you'll find the Tcl code I use to help me maintain this help notebook.) Here are some of the things you can do on your [User Code] page: * [Customizing the User Menu] * [Customizing the Edit Menu] * Write new commands for use in [Embedded Macro]s. * Write new commands for use in [Magic Button]s. See [Defining new commands] for more information.} 1072806780 #-------------------------------------------------- # User Interface Action page {User Interface Action} {A User Interface Action is an operation which can be invoked from a menu item, a keystroke, or by selecting File/Invoke Action and entering its name at the prompt. In a future version of Notebook it will might be possible to redefine the mapping between menus, keystrokes, toolbar buttons, and the actions they invoke. See [User Interface Actions] for a complete list.} 1072724684 #-------------------------------------------------- # User Interface Actions page {User Interface Actions} {The following "user interface actions" can be invoked by selecting File/Invoke Action from the application menu and then typing the action name at the prompt. While typing the action name, you can press Tab and Notebook will attempt to complete your partial response. Each of these actions has an associated [Notebook Command]; in most cases the name of the action and the command are identical. In a few cases, a number of actions map to a single command. The only difference between invoking an action using File/Invoke Action and calling it as a command is that the action will always prompt for any needed inputs whereas the inputs can usually also be passed explicitly to the command. See also [Deprecated Actions]. [@linktable { about-notebook back-page cancel-edits close-window copy-page-as-expanded-markup copy-page-as-html-page copy-page-as-html-text copy-page-as-mediawiki copy-page-as-plain-text copy-page-as-raw-markup copy-string cut-string copy-this-page-as-expanded-markup copy-this-page-as-html-page copy-this-page-as-html-text copy-this-page-as-mediawiki copy-this-page-as-plain-text copy-this-page-as-raw-markup cycle-recent-pages delete-page delete-pages edit-page edit-preferences edit-this-page export-page-as-expanded-markup export-page-as-html-page export-page-as-html-text export-page-as-mediawiki export-page-as-plain-text export-page-as-raw-markup export-this-page-as-expanded-markup export-this-page-as-html-page export-this-page-as-html-text export-this-page-as-mediawiki export-this-page-as-plain-text export-this-page-as-raw-markup find-string find-again forward-page goto-home goto-next-page goto-page goto-previous-page goto-user-code help-on help-index help-introduction help-on-actions help-on-commands help-on-markup insert-page load-page load-this-page load-user-code message-log new-notebook new-window notebook-license notebook-release-notes open-notebook paste-string redo-change refresh-this-page rename-page rename-this-page replace-string request-action save-and-continue save-edits show-index show-recent show-version sidebar-byname sidebar-bytime sidebar-close sidebar-open undo-change }@]} 1116795329 #-------------------------------------------------- # User Preferences page {User Preferences} {The File / Preferences menu item pops up Notebook's Preferences window box. The dialog box has one tab for each of the following areas: * [Font Preferences] * [Color Preferences] * [Editor Preferences] * [Miscellaneous Preferences] * [Tcl/Tk Preferences] * [Scaling Preferences] Make any desired changes, and then press Apply to apply them. Press Reset to abandon your changes and try again.} 1117470035 #-------------------------------------------------- # usermenu page usermenu {#rem command = Syntax = [@signature usermenu@] = Description = Allows the user to define the items for the "User Menu". The User Menu pops up when the user right-clicks on a browsed page. The menulist is a list of item definitions. Each item is defined by its name and a script of commands to execute. The usermenu command shown below defined three items, labeled "Edit Home", "View To Do", and "Edit To Do", respectively; the script which follows each label is executed when the item is selected. If the label is "separator" then a separator is added to the menu instead of a normal item; in this case the script of commands is ignored. = Examples = #pre usermenu { "Back" {back-page} "Forward" {forward-page} separator {} "Edit Home" {edit-page Home} "View To Do" {goto-page "To Do"} "Edit To Do" {edit-page "To Do"} } #unpre = Implementation = [@showproc usermenu@]} 1114962122 #-------------------------------------------------- # version page version {#rem command = Syntax = version = Description = Returns the version number of the Notebook application. = Examples = The following [embedded macro] inserts the version number into a page: #pre [@lb@]version[@rb@] #unpre It looks like this: '[@version@]'. = Implementation = [@showproc version@]} 1114962125 #-------------------------------------------------- # Welcomer page Welcomer {If you invoke Notebook without specifying a notebook file, the first thing you'll see will be the "Welcome To Notebook" window. By clicking on the [magic button]s in the window, you can: * Create a new notebook file * Open an existing notebook file * Browse the on-line help And of course, you also have access to all of Notebook's menus.} 1072802633 #-------------------------------------------------- # Window Menu page {Window Menu} {The Window menu has the following items; the related [User Interface Action] is listed after each in parentheses. * Window / Message Log ([message-log])
Pops up the [Message Log] window. * Window / Window Name
Raises the named window to the front of the screen.} 1114966723 # End of Notebook Database File