Source

tkf.bitbucket.org / neorg-doc / _sources / index.txt

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
.. contents::

=========================
  NEOrg Reference Guide
=========================


.. _special-directives:

Special directives
==================

A :term:`directive` is a general `reStructuredText`_ block markup.
With the special directives defined by NEOrg, you can fetch data and
images, show them effectively, and organize your notes.


Show data in a table - :rst:dir:`table-data`
--------------------------------------------

.. rst:directive:: .. table-data:: path [path ...]

   Search data file under the given list of `path` and show matched
   data.
   You can use :term:`Unix shell-style pattern matching`.

   base : string (newlines removed)
       This is an optional parameter to specify the directory
       where the data files are searched from.
       The data files will be searched from :envvar:`DATADIRPATH` if
       not specified.

       For example,

       .. sourcecode:: rst

           .. table-data:: 2011-02-*/data.json
                           2011-03-*/data.json
              :base: my/experiment

       will search the files matches to
       ``my/experiment/2011-02-*/data.json`` and
       ``my/experiment/2011-03-*/data.json``.

   data : text [, text, ...]
       A comma- or space-separated list of the :term:`dictionary path`.
       You can use :term:`Unix shell-style pattern matching`.

   widths : integer [, integer...]
       A comma- or space-separated list of relative column widths.

   link : text [, text]
       A comma- or space-separated list of path to the link(s).
       Magic words ``%(path)s`` and ``%(relpath)s`` are available.

       ``%(path)s``
           This represents full path to the parent directory of the
           data file.
       ``%(relpath)s``
           This is the relative path of the ``%(path)s`` from the
           :term:`base` directory.

   path-order : {'sort', 'sort_r'}
       Sort the matched data paths.
       ``sort`` will sort the paths in alphabetical order
       and ``sort_r`` is the reversed version of ``sort``.
       The default is ``'sort'``.
       Note that

       .. sourcecode:: rst

           .. table-data:: 2011-02-*/data.json
                           2011-03-*/data.json
              :path-order: sort_r

       does not makes ``2011-03-01/data.json`` higher than
       ``2011-02-01/data.json``.  You will need to write

       .. sourcecode:: rst

           .. table-data:: 2011-03-*/data.json
                           2011-02-*/data.json
              :path-order: sort_r

   trans : flag
       Transpose the table.

   .. seealso:: :ref:`examples/table-data`


Show data and images in a table - :rst:dir:`table-data-and-image`
-----------------------------------------------------------------

.. rst:directive:: .. table-data-and-image:: path [path ...]

   Search data under the given list of `path` and show matched data and
   corresponding image(s).
   You can use :term:`Unix shell-style pattern matching`.

   base : string (newlines removed)
       This is an optional parameter to specify the directory
       where the data files are searched from.
       See :rst:dir:`table-data` for the details.

   data : text [, text, ...]
       A comma- or space-separated list of the :term:`dictionary path`.
       See :rst:dir:`table-data` for the details.

   image : text [, text, ...]
       A comma- or space-separated list of path to the images.
       The path is the relative path from the parent directory of
       the data file.

   widths : integer [, integer...]
       A comma- or space-separated list of relative column widths.
       Note that the first column is data sub-table and the second and
       the after are the images specified in `:image:`.

   image-{OPTION} : integer:{VAL} [, integer:{VAL} ...]
       `integer` is the index of the image.
       `{VAL}` specifies the value of the `{OPTION}` of the
       `image directive`_.

   link : text [, text]
       A comma- or space-separated list of path to the link(s).
       See :rst:dir:`table-data` for the details.

   path-order : {'sort', 'sort_r'}
       Sort the matched data paths.
       See :rst:dir:`table-data` for the details.

   sort : text [, text]
       A comma- or space-separated list of the :term:`dictionary path`.
       The table will be sorted by values of the keys.

   .. seealso:: :ref:`examples/table-data-and-image`

.. _`image directive`:
   http://docutils.sourceforge.net/docs/ref/rst/directives.html#image


See the difference of data - :rst:dir:`dictdiff`
------------------------------------------------

.. rst:directive:: .. dictdiff:: path [path ...]

   Search data under the given list of `path` and show the difference
   of the data.
   You can use :term:`Unix shell-style pattern matching`.

   base : string (newlines removed)
       This is an optional parameter to specify the directory
       where the data files are searched from.
       See :rst:dir:`table-data` for the details.

   link : text [, text]
       A comma- or space-separated list of path to the link(s).
       See :rst:dir:`table-data` for the details.

   include : text [, text]
       A comma- or space-separated list of :term:`regular expression`
       of the :term:`dictionary path` to include.

   exclude : text [, text]
       A comma- or space-separated list of :term:`regular expression`
       of the :term:`dictionary path` to exclude.

   path-order : {'sort', 'sort_r'}
       Sort the matched data paths.
       See :rst:dir:`table-data` for the details.

   trans : flag
       Transpose the table.

   .. seealso:: :ref:`examples/dictdiff`


Show effects of the parameter change - :rst:dir:`grid-images`
-------------------------------------------------------------

.. rst:directive:: .. grid-images:: path [path ...]

   Search data and show the images related to the data on "**grid**".
   You can use :term:`Unix shell-style pattern matching`.

   In experiments, you may change parameters systematically
   to see what will happen.  For example, when you do experiments
   varying two parameters *a=1, 2, 3* and *b=0.1, 0.2, 0.3*,
   you will get 9 results.  Viewing the results in a linear list is
   a bad idea: you should see it in a 3x3 matrix like this!:

   .. list-table::
      :widths: 1 5 5 5

      * -
        - **b=0.1**
        - **b=0.2**
        - **b=0.3**
      * - **a=1**
        - result with *a=1* and *b=0.1*
        - result with *a=1* and *b=0.2*
        - result with *a=1* and *b=0.3*
      * - **a=2**
        - result with *a=2* and *b=0.1*
        - result with *a=2* and *b=0.2*
        - result with *a=2* and *b=0.3*
      * - **a=3**
        - result with *a=3* and *b=0.1*
        - result with *a=3* and *b=0.2*
        - result with *a=3* and *b=0.3*

   The grid is a N-dimensional version of this matrix.
   To see it in 2D display (because we don't have N-dim display),
   NEOrg generates the nested table.

   base : string (newlines removed)
       The base path for searching data. Real path to be used
       This is an optional parameter to specify the directory
       where the data files are searched from.
       See :rst:dir:`table-data` for the details.

   param : text [, text]
       A comma- or space-separated list of the :term:`dictionary path`
       for the axes of the grid.

   image : text [, text]
       A comma- or space-separated list of path to the images.
       The path is the relative path from the parent directory of
       the data file.

   .. seealso:: :ref:`examples/grid-images`


Find images - :rst:dir:`find-images`
------------------------------------

.. rst:directive:: .. find-images:: path [path ...]

   Search images under the given list of `path` and show matched images.
   You can use :term:`Unix shell-style pattern matching`.

   base : string (newlines removed)
       This is an optional parameter to specify the directory
       where the data files are searched from.
       See :rst:dir:`table-data` for the details.

   .. seealso:: :ref:`examples/find-images`


List Pages - :rst:dir:`list-pages`
----------------------------------

.. rst:directive:: .. list-pages::

   Insert list of sub-pages.


.. _template-page:

Template page - ``_temp_``
==========================

When you do experiments repeatedly, you may want to see the results
in a fixed format.  The template page can be used for that purpose.

The page which has ``_temp_`` in its :term:`page path` is a
:term:`template page`.
The template page is used for generating page.
If the page path does not exist but the template page which matches to
the page path exists, generated page will be shown.

Examples of the template :term:`page path`:

    (a) ``/my/page/_temp_/``
    (b) ``/my/page/_temp_/_temp_/``
    (c) ``/my/page/_temp_/images/``
    (d) ``/my/page/_temp_/subdata/_temp_/``
    (e) ``/my/page/_temp_/_temp_/subdata``

    * ``/my/page/2011-05-21/`` matches to (a)
    * ``/my/page/2011-05-21/some-data/`` matches to (b)
    * ``/my/page/2011-05-21/images/`` matches to (c)
    * ``/my/page/2011-05-21/subdata/000/`` matches to (d)
    * ``/my/page/2011-05-21/000/subdata/`` matches to (e)
    * ``/my/page/2011-05-21/subdata/subdata/`` matches to (e)


``{{ args[N] }}`` (where ``N`` is an integer)
    N-th replacement of the ``_temp_`` in the URL.
    For example, at the page ``/my/page/2011-05-21/subdata/000/``
    in the above example, ``{{ args[0] }}`` and ``{{ args[1] }}``
    will be replaced by ``2011-05-21`` and ``000``.

``{{ path }}``
    This will be replaced by the full path to this directory.

``{{ relpath }}``
    This will be replaced by the relative path from the parent page of
    the leftmost ``_temp_`` page.

.. seealso:: :ref:`examples/template-page`


Searching Pages
===============

NEOrg has Whoosh_ powered searching functionality.
For the full description of the query language, see
`The default query language --- Whoosh documentation`_.
The following are quick examples:

.. list-table:: Query examples
   :header-rows: 1
   :widths: 1 2

   * - Query
     - Meaning
   * - ``alpha AND beta``
     -
   * - ``alpha beta``
     - equivalent to ``alpha AND beta``
   * - ``alpha NOT (beta OR gamma)``
     -
   * - ``page_path:MyPage``
     - use :term:`page path` in the search query
   * - ``page_path:(MyPage SubPage)``
     - equivalent to ``page_path:MyPage page_path:SubPage``
   * - ``te?t test* *b?g*``
     - use :term:`unix shell-style pattern matching`
   * - ``ninja^2 cowboy bear^0.5``
     - importance: ninja = 2*cowboy = 4*bear


.. _`The default query language --- Whoosh documentation`:
   http://packages.python.org/Whoosh/querylang.html
.. _Whoosh: https://bitbucket.org/mchaput/whoosh/wiki/Home


Glossary
========

.. glossary::

   directive
       A directive is one of the `reStructuredText`_ block markup in
       the following shape:

       .. sourcecode:: rst

          .. directive-name:: argument(s)
             :option: parameter
             :another_option: another_parameter

             some contents

       See `reStructuredText Directives`_ for more information and
       the basic directives defined by docutils.

       NEOrg defines various special for displaying and organizing
       data effectively (see :ref:`special-directives`).

   page path
       The page path is the URL to the page.

   unix shell-style pattern matching
       Unix shell-style pattern matching supports the following
       wild-cards.

       +------------+------------------------------------+
       | Pattern    | Meaning                            |
       +============+====================================+
       | ``*``      | matches everything                 |
       +------------+------------------------------------+
       | ``?``      | matches any single character       |
       +------------+------------------------------------+
       | ``[seq]``  | matches any character in *seq*     |
       +------------+------------------------------------+
       | ``[!seq]`` | matches any character not in *seq* |
       +------------+------------------------------------+

   ``base``
       This is the optional parameter for the directives which searches
       the data files.
       See :rst:dir:`table-data` for the details.

   ``link``
       This is the optional parameter for the directives which generates
       the links to the other pages.
       See :rst:dir:`table-data` for the details.

   magic words
       Magic words are the special words which are replaced by NEOrg.

       Magic words ``%(path)s`` and ``%(relpath)s`` are available
       in the :term:`link` parameter.

       Magic words ``%(root)s`` and ``%(neorg)s`` are available in the
       configuration file for the variables :envvar:`DATADIRPATH` and
       :envvar:`DATABASE`.

   dictionary path
       To specify the value in the nested dictionary, NEOrg uses
       period-separated keys.  For example, the values in the
       following nested dictionary can be accessed by the
       "dictionary path" such as ``'key1.nestedkey1'``.

       .. sourcecode:: js

          {'key1': {
               'nestedkey1': 1,
               'nestedkey2': 2
           }
           'key2': 2
          }

   regular expression
       NEOrg uses python regular expression to filtering out/in
       :term:`dictionary path`.

       See `Regular Expression Syntax --- Python documentation`_ for
       more information about the regular expression syntax.

   template page
       A template page is the page which has at least one ``_temp_``
       in its :term:`page path`.
       See also :ref:`template-page`.

   debug mode
       In debug mode, python interactive shell will be invoked in your
       browser when NEOrg clashes.
       See `Debugging Applications -- Werkzeug documentation`_ and
       `Debug Mode --- Flask documentation`_  for more information.

       .. warning::

          If someone can access to the
          NEOrg running in debug mode, he can do anything your python
          can do, such as deleting files.  Thus, **debug mode should
          not be used on an untrusted network.**

.. _`Regular Expression Syntax --- Python documentation`:
   http://docs.python.org/library/re.html#re-syntax
.. _`Debugging Applications -- Werkzeug documentation`:
   http://werkzeug.pocoo.org/docs/debug/
.. _`Debug Mode --- Flask documentation`:
   http://flask.pocoo.org/docs/quickstart/#debug-mode


Configuration variables
=======================

.. envvar:: DATADIRPATH

   Path to your data directory.
   :term:`Magic words` ``%(root)s`` and ``%(neorg)s`` are available.
   The string ``~`` will be replaced by the user's home directory.
   Also, the environment variables are available.  For example, you
   can also use ``$HOME`` or ``${HOME}`` to specify your home directory.
   The default is ``%(root)s``.

   ``%(root)s``
       The directory you specified by ``neorg init`` command.
       If you did not specify, this is the directory where you ran
       ``neorg init`` command.

   ``%(neorg)s``
       This is equivalent to ``%(root)s/.neorg/``.

.. envvar:: DATABASE

   The path to the sqlite data base file.
   :term:`Magic words` ``%(root)s`` and ``%(neorg)s``,
   special character ``~``, and the environment variables are available.
   The default is ``'%(neorg)s/neorg.db'``.

.. envvar:: DEBUG

   If it is set to ``True``, ``neorg serve`` runs in :term:`debug mode`
   always.


FAQs
====

How do I make a new page?
-------------------------

Just type a page path to the browser's address bar, e.g.::

    http://localhost:8000/my/new/page/

and then you will see the edit form, if the page does not exist.


How do I make a link to the other page?
---------------------------------------

If a string starts with ``/``, ``./`` or ``../``, ends with ``/``
and contains only alphabets, numbers and ``_.+-``` then it will
be regarded as a link.  For example::

    /full/path/link/
    ./link/to/a/sub/page/
    ../link/to/a/sibling/page/

Note that this markup is weaker than any other `reStructuredText`_
markups.  For example, the following is not regraded as a link::

    /texsts_with_a_-hyphen-after-the-under_score/

This is because ``texsts_with_a_`` is regraded as a hyper linke
target (and you will get a "Docutils Sysmtem Message" unexpectedly!).
You should escape the "tailing" underscore ``_`` with a slash ``\``
like this::

    /texsts_with_a\_-hyphen-after-the-under_score/


Docuitils links
===============

- `Docutils Project Documentation Overview`_

  - `reStructuredText`_

    - `A ReStructuredText Primer`_
    - `Quick reStructuredText`_
    - `reStructuredText Cheat Sheet (text only)`_
    - `reStructuredText Demonstration`_
    - `reStructuredText Markup Specification`_
    - `reStructuredText Directives`_
    - `reStructuredText Interpreted Text Roles`_


.. _`Docutils Project Documentation Overview`:
   http://docutils.sourceforge.net/docs/

.. _`reStructuredText`:
   http://docutils.sourceforge.net/rst.html

.. _`A ReStructuredText Primer`:
   http://docutils.sourceforge.net/docs/user/rst/quickstart.html
.. _`Quick reStructuredText`:
   http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`reStructuredText Cheat Sheet (text only)`:
   http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
.. _`reStructuredText Demonstration`:
   http://docutils.sourceforge.net/docs/user/rst/demo.html
.. _`reStructuredText Markup Specification`:
   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
.. _`reStructuredText Interpreted Text Roles`:
   http://docutils.sourceforge.net/docs/ref/rst/roles.html
.. _`reStructuredText Directives`:
   http://docutils.sourceforge.net/docs/ref/rst/directives.html


Other contents
==============

.. toctree::
   :maxdepth: 1

   examples
   commands
   changelog
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.