Skip to content

Home

Jump to bottom
Massimo Nardello edited this page Jun 10, 2024 · 6 revisions

pgNotex user manual

Copyright Massimo Nardello, Modena (Italy) 2020-2024.

A free software for macOS to manage textual notes in Markdown, tasks, and files using PostgreSQL 16.

The current version of the software is 1.5.0.3 published on June 10 2024.

pgNotex is free software, as it is released under the GPL version 3 license or following, available on www.gnu.org/licenses/gpl-3.0.html.

This manual of pgNotex is available within the software as well, and also in pdf format in https://github.com/maxnd/pgNotex/blob/main/manuals/pgnotex-manual.pdf. The software runs in English and Italian.

Before contributing to the development of this software, see the Contributing file.

The software looks like this, with one possible color setting:

Introduction

pgNotex is a free software for macOS useful to manage many textual notes in Markdown, tasks and documents on a single computer or in a local network using the open-source database PostgreSQL 16 or following (https://www.postgresql.org/).

The notes are divided into notebooks and, within them, in sections, and it is possible to associate to each note a list of activities to be done, a series of attachments (files of any kind), tags and links to other notes. The search function may find the notes starting from the title, the text, the modification date, the tags, the name of the attachments or activities. Files of Microsoft Word (docx), LibreOffice Writer (odt) and in plain text (txt) can be imported as plain text in a new note, while in the first two cases the original file is attached to it.

The text can be easily converted to many other formats, like Microsoft Word or LibreOffice Writer’s, using Pandoc (https://pandoc.org/), that must be installed in the computer in use. The software interface is in English and Italian.

The aim of pgNotex is to guarantee maximum reliability and excellent performance even in presence of a very consistent amount of data. The use of PostgreSQL grants the required reliability with respect to file-based solutions, while maintaining excellent performance even with many data and using just about 60 MB pf memory. The use of the Markdown format for the text of the notes allows to store them in the database exactly as they are written, speeding up their saving and loading, and allowing a very quick search within them. Furthermore, this format is unique on all platforms and gives the possibility to export data to other software very easily.

pgNotex has been written with Lazarus (www.lazarus-ide.org) and accesses the PostgreSQL database through the Zeos components (sourceforge.net/projects/zeoslib). pgNotex is free software, as it is released under the GPL version 3 license or following, available on www.gnu.org/licenses/gpl-3.0.html, which the user must accept in order to use it.

This manual does not deal with the installation and use of PostgreSQL and Pandoc. See their websites and manuals for all the information needed. On this site, in the folder Data of the source code, there is a backup file without data that can be restored in a new PostgreSQL database and used by pgNotex.

General notes

Interface

Data are arranged into notebooks (grid on the top left). Each notebook contains many sections (center left grid), and each section contains many notes (bottom left grid). Notebooks, sections, and notes are identified by an identification number (ID), i.e., a number assigned automatically by the software and not editable by the user. It is used to indicate a specific notebook under which to move the current section, or a specific section under which to move the current note, or to link two different notes.

When a notebook or section are created, the software shows the details form, which allows to indicate its title and possibly some explanatory notes. In the field of explanatory notes, Command + Return saves the data and closes the form. These notes are visible only within this form, but can be viewed again with the Details menu item (see below). Typing Command + Return in the Title field, the software inserts the title of the note in its text, as title.

The name of the attachments to the current note (top right grid) and of the tags (center right grid) can be changed also by selecting them in their own grid and pressing Return or F2. On the other hand, it is not possible to modify a link between two different notes because it is reciprocal – that is, the software automatically inserts a further link in the note to which the one in use is connected – so that any change in one of the two links would leave the other orphaned. For this reason, to modify a link it’s necessary to delete it and create it again to a different note.

Double click on the grid of notebooks or sections opens the details form. The same action on the grid of attachments opens the current attachment, while on the links grid brings to the linked note.

It is possible to add a bookmark to the current note with the shortcut Command + Alt and a number from 1 to 9. Then, to move to that note, type Command and the previously assigned number. Bookmarks can also be viewed, set, and deleted using the form displayed with the Edit - Bookmarks menu item. A bookmark may be deleted also with the shortcut Fn + Backspace.

The four columns of the grid visible in this form show the bookmark number (1 to 9), the title of the notebook, of the section and of the note associated to the bookmark. The Set button associates the current note with the bookmark number of the selected row, Clear deletes the content of the selected row, Up and Down move he current bookmark up or down, Close closes the form without doing anything and Go to – like with double click or pressing Return – finds the note which the bookmark of the selected row is linked to. Bookmarks are remembered by the software after exiting the software and are relative to the database in use.

In the text of the notes, the following shortcuts are available:

  • Command + Shift + Backspace: delete the current paragraph.
  • Command + “+” (“plus” character): enlarge the character of the text of the notes and of the list of titles (see below).
  • Command + “-” (“less” character): reduce the character of the text of the notes and of the list of titles (see below).
  • Command + Control + “+” (“plus” character): enlarge the linespacing of the text of the notes.
  • Command + Control + “-” (“less” character): reduce the linespacing of the text of the notes.
  • Command + Options + Control + “+” (“plus” character): enlarge the space among paragraphs of the text of the notes.
  • Command + Options + Control + “-” (“less” character): reduce the space among paragraphs of the text of the notes.
  • Command + Option + Z: undo the last changes made to the text of the current notes and not yet saved.
  • Command + Z: undo the last change to the text of the notes.
  • Command + Shift + Y: redo the last change to the text of the notes.
  • Command + Option + Up arrow: move the current paragraph up.
  • Command + Option + Down arrow: move the current paragraph down.
  • Command + Ctrl + Up arrow: on a title, move it before the previous title of the same level along with the possible subtitles and text.
  • Command + Ctrl + Down arrow: on a title, move it after the following title of the same level along with the possible subtitles and text.
  • Command + Ctrl + Left arrow: on a title, remove one hash at the beginning, to promote it to a higher level.
  • Command + Ctrl + Right arrow: on a title, add one hash at the beginning, to demote it to a lower level.
  • Command + Option + “.” (dot): format as a list the current paragraph and those above and below up to the first empty line, using subsequently the asterisk, the bullet, the line, the plus, the number and nothing as beginning of the list items.
  • Command + Option + A: insert the current date in the text of the notes.
  • Command + Option + Shift + A: insert the current date and time in the text of the notes.
  • Command + “;”: highlight the current paragraph for a second and move the cursor to the next one; it’s useful while showing the text of the note to other people in a presentation.
  • Command + Option + F:
    • within the footnote reference in the text (e.g. [^1]): move the cursor to the footnote;
    • within the footnote (e.g. [^1]: This is the footnote): move the cursor to the footnote reference in the text;
    • in other positions: create a new footnote reference and a new footnote, both properly numbered.

Furthermore, it’s possible to move to the previous or next note in the current section with Command + Page Up and Command + Page Down, to move to the previous or next section with Command + Shift + Page Up and Command + Shift + Page Down, and to move to the previous or next notebook with Command + Option + Shift + Page Up and Command + Option + Shift + Page Down. To select the panel of the notes or of the tasks, the shortcuts Command + Y and Command + Option + Y may be used.

The text of the notes must be composed in Markdown. The following markers are formatted with a different color:

  • titles: e.g. # Title 1, ## Title 2, ### Title 3, #### Title 4, ##### Title 5, ###### Title 6
  • links to websites: e.g. [My website](www.mywebsite.it)
  • links to pictures: e.g. [My picture](img.png)
  • footnotes: e.g. [^1] in the text and [^1]: at the bottom of the text, or ^[text of the footnote] for inline footnotes
  • lists: e.g. *[tab]list item, •[tab]list item, +[tab]list item, -[tab]list item, 1.[tab]list item

In the lists, the headers expected by Markdown, i.e. “-”, “+”, “*”, “•” or progressive numbering, must be followed by a tab. The software generates a new item in the list when Enter is pressed. If the current element is empty, the header is removed.

Some Markdown markers are not visible because the text inside them is formatted:

  • italics: e.g. *this is italics*
  • bold: e.g. **this is bold**
  • bold italics: e.g. ***this is bold and italics***
  • strikethrough: e.g. ~~this is strikethrough~~
  • code: e.g. `this is code`
  • quotation: e.g. > this is quotation

The text of the notes must be typed in Markdown according to the style of Pandoc (https://pandoc.org/MANUAL.html#pandocs-markdown). Anyway, even paragraphs not separated by an empty line will be recognized by Pandoc as different. Furthermore, also the bullet (•) may be used as header of a list item.

Some invisible characters may mess the formatting of the text of the notes. If this happens, clean the text with the Edit - Reorder text menu item.

To renumber the footnotes in the text, use the Edit – Reorder text menu item. Possible footnotes that had not a reference in the text of the note will be renumbered adding 10,000 to their number to let the user identify them.

The Edit – Reorder text menu item is useful also to correctly renumber the numbered lists and footnotes if the user had changed their numbering.

To insert in the text of the current note a link to an attached picture or file, use the proper Markdown syntax, but do not add any path to the picture or file, like this: ![My picture](image 10.jpg), or [My file](my file.docx). When the note will be exported to the Word format in the Download directory, the picture or the file will be located correctly, since Pandoc will be called with the option --resource-path= set to the Downloads directory.

The status bar shows the date and time of the last modification to the current note and the number of its characters (markers included), and on the right, the date and the hour. The green or red circle on the right indicates if data have been saved or if there are changes not yet saved.

Tasks

Each note can be associated to different activities shown in the Tasks section in the tab at the top. The number of activities, if present, is shown next to the title of the tab after three bullets. In the activity grid it is possible to indicate the name of an activity, its possible start and end date (i.e., the deadline), if it has been completed, its priority and the resources, i.e., the people who are in charge of carrying it out. By typing a space in the date fields, the initial one is filled with the current date, while the final one is postponed by 7 days. Using the arrows left and right keys while holding down Shift, the two dates move forward and backward. Typing a space in the Priority field changes its value. Finally, the activities carried out are displayed in green, those without date or not started are in black or white, those started in blue and those that have expired and not completed in red.

The activities can be inserted and deleted with the proper menu items (see below), but with Ctrl + Del the current one can be quickly deleted. In the field below the activity grid, it’s possible to enter explanatory notes related to the current activity. Finally, the activities are sorted automatically by final date (deadline), start date and priority, leaving at the bottom those which have been completed. To move up and down an activity, change its dates or priority accordingly. To sort the activity after having modified them, use the menu item Notes – Tasks – Sort.

To display a grid containing the activities of all the notes, use the menu item Notes - Show all tasks.

By double-clicking or pressing Return on an activity, the software selects the note to which it belongs and then shows the activity itself. To show also the completed tasks, click on the check box Show completed tasks.

Titles

At the left of the text of the notes there is a section that is automatically filled in by the software with the titles contained in the note and defined in Markdown format, that is preceded by one to six hashes (#) followed by a space. This list may be refreshed with the menu item Edit – Update text and titles. Clicking on a title name in this section selects it in the text of the note. This list is also useful to get immediately the main contents of a note.

Menu items

The functions related to the menu items are summarized here. Note that pop-up menus, displayed with a right-click, are available on some grids, and replicates some of the items of the main menus.

File menu

  • Save: save all data in the database.
  • Undo changes: undo any change made to the data and recover the last saved version.
  • Refresh: update the database data, to view the changes made by other users in a local network.
  • Export notes of current section: create a text file containing the data of the notes of the current section, of the related tasks, tags and attachments; these attachments, if present, are saved in a folder with the same name of the file.
  • Import notes in current section: import a file created with the previous functionality, containing notes with the related tasks, tags and attachments, into the current section.
  • Close database: close the database and return to login.
  • Quit: exit pgNotex.

Edit menu

  • Cut: cut the selected in text in the clipboard.
  • Copy: copy the selected text in the clipboard.
  • Paste: paste the text contained in the clipboard.
  • Select all: select all the text of the current note.
  • Update text and titles: compile the list of the titles and format them in the text of the current note.
  • Reorder text: delete all possible characters in the text of the current note which prevents its proper formatting, reorder the numbering of the footnotes and of the numeric lists, compile the list of the titles and format them.
  • Encode selected link: if a link is selected, encode the “(” characters with %28, the “)” characters with %29 and the space characters with %20, so that the brackets are not confused with the Markdown markers and the spaces with the end of the link.
  • Preview picture: when the cursor is inside a link to a picture whose file is attached, show the preview of the picture in a popup box; this box is close automatically after 2 seconds, or pressing Esc.
  • Open with Pandoc: save in the Downloads directory a file containing the text of the current note converted in another format with Pandoc. The format could be defined in the options of the software (see below).
  • Show bookmarks: show the form for managing bookmarks (see above).

Notebooks menu

  • New: create a new notebook and open the details form to type its title and any comment.
  • Delete: delete the current notebook, with all the sections and notes related to it.
  • Sort by: sort the notebooks as set by the user (Custom item) or by title (Title item); the user can set the position of a notebook in the notebooks grid with the following menu item.
  • Move: move the current notebook up (Up item) or down (Down item) in the notebook grid.
  • Details: open the details form with the data of the current notebook, containing its ID, its title and some notes.
  • Copy ID: copy the ID of the current notebook in the clipboard.

Sections menu

  • New: create a new section and open the details form to type its title and any comment.
  • Delete: delete the current section, with all the notes related to it.
  • Sort by: sort the sections as set by the user (Custom item) or by title (Title item); the user can set the position of a section in the sections grid with the following menu item.
  • Move: move the current section up (Up item) or down (Down item) in the sections grid.
  • Details: open the details form with the data of the current section, containing its ID, its title and some notes.
  • Change notebook: open a form to enter the ID of a notebook in order to move the current section under it; the Paste button or the shortcut Command + V allow to paste the ID already copied in the clipboard, and to show the name of the associated notebook in a label.
  • Copy ID: copy the ID of the current section.

Notes menu

  • New: create a new note.
  • Delete: delete the current note, with any possible attachments, tags and links.
  • Sort by: sort the notes as set by the user (Custom item), by title (Title item) or by modification date (Modification date item); the user can set the position of a note in the notes grid with the following menu item.
  • Move: move the current note up (Up item) or down (Down item) in the notes grid.
  • Attachments: attach one or more files of any kind to the current note (New item), delete the current one (Delete item), open it (Open item), save it (Save as item), save it in the Downloads folder (Save in Downloads item), replace the current attachment with the one having the same name in the Downloads folder (Load from Downloads item) and insert its name in the text of the current note (Insert name item); it’s possible to attach files also by dragging them onto the main form of the software when a note is active.
  • Tags: create a new tag related to the current note (New item), delete the current one (Delete item), rename a tag in all the notes of the database (Rename tag item) and delete the possible empty tags created by error (Delete empty tags item); it’s possible to add a new tag in the current note also selecting it in the tags list within the Search section and using the popup menu Insert tag in current note, or, if the tags list is selected, also with menu item at stake or its shortcut (Command + T).
  • Links: open a form to enter the ID of an existing note to link it to the current one, simultaneously creating a link to the latter in the first one (New item), delete the current link and the corresponding one in the linked note (Delete item) and find the linked note (Locate linked note item); this last operation can also be carried out by double-clicking on the link.
  • Tasks: create a new activity (New item), delete the current one (Delete item), sort the activities after changes (Sort item) and hide the completed activities (Hide done tasks item).
  • Show all tasks: open a grid containing all the activities of all the notes in the database; the notes are not editable, but double clicking on one of them brings to the note that contains it.
  • Import from file: import a Microsoft Word file (with the extension .docx and not .doc), LibreOffice Writer file (with the extension .odt) or a file in plain text (with the extension .txt) into a new note; except in this last case, the original file is attached to the note, while its content is always imported as note text, without formatting.
  • Change section: open a form to enter the ID of a section in order to move the current note under it; the Paste button or the shortcut Command + V allow to paste the ID already copied in the clipboard, and to show the name of the associated section in a label.
  • Copy ID: copy the ID of the current note.
  • Search in note: find the first occurrence – with the proper button or pressing Return in the field Text to find – or the following – with the proper button or pressing Command + Return in the field Text to find – of a text within the current note, or replace all its occurrences with another text; search and replace are not case sensitive; when the replace functionality is used, the code \n is a substitute for the paragraph break, while the code \t of the tabulation, both in the Text to find and in the Replace with fields.
  • Find: open the section of the software dedicated to data search (see below some notes on its use).

Tools menu

  • Show editor only: display only the text of the current note and the list of titles, to focus on what is written.

  • Full screen: display the interface of the software at full screen.

  • Transparency: activate a level of transparency (high, middle, low, none) of the main interface of the software.

  • Run another instance: run another instance of the app.

  • Options: open the options form. In this mask it’s possible:

    • specify the font name of the notes and titles text (Font name of notes and titles box);
    • restore the default colors (Default colors button);
    • specify the color of the titles 1 (Titles 1 color button);
    • specify the color of the titles 2 (Titles 2 color button);
    • specify the color of the titles 3-6 (Titles 3-6 color button);
    • specify the color of the titles (Titles color button);
    • specify the font size of the text of the notes (Font size of the notes field);
    • specify the font size of the titles (Font size of the titles box);
    • specify the maximum size of note text beyond which titles are not formatted for performance reasons (Max number of characters field);
    • specify the line spacing (Line spacing field);
    • specify the paragraph spacing (Paragraph spacing field);
    • specify if the titles must be numbered (Number titles check box);
    • specify if the data must be automatically saved every minute (Save every minute check box);
    • specify the path of the client library of PostgreSQL (PostgreSQL library path box);
    • specify the server address, which is localhost for the use of pgNotex on a single computer, the IP address of the server in a local network (Server field);
    • specify the port on which the database receives connections, 0 for default (Port field);
    • specify the options of Pandoc (Options of Pandoc field);
    • specify the path of the executable of Pandoc (Path of Pandoc field);
    • specify the template used by Pandoc as a model for conversion of the text of the notes (Template field);
    • specify the format of the output file (Output file field).

Search

The Notes - Find menu item opens the form to find the notes. In the box at the top left of the find section may be specified the field in which to search:

  • Title contains, to select the notes whose title contains the text inserted in the field below;
  • Text contains, to select the notes whose text contains the one inserted in the field below;
  • Modification date among, to select the notes whose modification date is among those inserted in the field below with the following format: 1/1/2019 - 2/1/2019 (therefore, the two dates are separated by space - dash - space); it’s possible to insert also today to select the notes edited on the current day, or yesterday to select the notes edited on the previous day;
  • Tags equal to, to select the notes of which at least one of the tags corresponds to one of those indicated in the field below, separated by commas and spaces (e.g. meetings, projects, elaborations);
  • Attachment name contains, to select all the notes in which the name of at least one of the attachments contains the text entered in the field below;
  • Activity name contains, to select all the notes in which the name of at least one of the activities contains the text entered in the field below;
  • SQL Where clause, to insert directly a SQL Where clause in the field below.

The SQL clause must not include the word where and can involve all the fields used in the database. Their list is this:

notebooks.id integer notebooks.title varchar notebooks.comments text sections.id integer sections.id_notebooks integer sections.title varchar sections.comments text notes.id integer notes.id_sections integer notes.title varchar notes.text text notes.modification_date timestamp tasks.id integer tasks.id_notes integer tasks.done smallint tasks.title varchar tasks.start_date date tasks.end_date date tasks.priority varchar tasks.resources varchar tasks.comments text attachments.id integer attachments.id_notes integer attachments.title varchar tags.id integer tags.id_notes integer tags.tag varchar links.id integer links.id_notes integer links.link_note integer

For example, a SQL clause may be:

notebooks.title like ‘%meetings%’ and notes.title like ‘%report%’

to select all the notes whose title contains report and in which the title of the relative notebook contains meetings. Consult the PostgreSQL guide for further indications on the use of SQL syntax.

In the combo box at the left of the Find button it’s possible to specify if the search must be done on the whole database, on the current notebook only or on the current section only.

At the right of the search field there is a list of all the tags used in the database sorted by name. With a double click or pressing Return on the list, the selected tag will be added to the text to be found. The list is updated when the search form is opened or with the popup menu item Update list. Typing a character when the list of the tags is selected, selects the first tag whose name starts with the same character.

Pressing Return in the search field or clicking the Find button, all the notes that meet the entered criteria are displayed in the grid on the right sorted by notebooks, sections and notes titles. Pressing Ctrl + Return instead inserts a new row in the search field, useful for entering fairly complex SQL clauses. Pressing Return in the search grid or double-clicking on it shows the corresponding note in the main interface of the software, so that it can be read or modified.

To clear the search, clear the content of the search field and press Return or click on the button Find.

Clone this wiki locally