Skip to content

Latest commit

 

History

History
495 lines (337 loc) · 14.9 KB

orgro-manual.org

File metadata and controls

495 lines (337 loc) · 14.9 KB
Raw

Welcome to Orgro

Orgro is an Org Mode file viewer.

Files open in “overview” visibility mode, with top sections folded.

Tap a section header to expand it ↓

Supported Org Mode features

Orgro can understand the following Org Mode features:

Sections

TODO keywords, priority markers, and tags are highlighted and laid out nicely.

You can perform these actions on a section:

  • Open and close by touching the section headline
  • Long tap the headline to narrow to that section
  • Slide a section from right to left to cycle the TODO keyword
    • Statistics cookies are updated automatically

Blocks

Blocks are laid out with horizontal scroll to keep code readable. They can also be opened and closed just like sections by touching the block header.

(+ 1 2)

The example above also illustrates affiliated keywords (the #+RESULTS: line) and fixed-width areas (the : 3 line). Fixed width areas also have horizontal scroll to ensure proper display.

Diminish meta lines like #+RESULTS: with Reader Mode.

Syntax highlighting

Syntax highlighting is applied for many languages in src blocks.

#!/bin/bash

###### CONFIG
ACCEPTED_HOSTS="/root/.hag_accepted.conf"
BE_VERBOSE=false

if [ "$UID" -ne 0 ]
then
 echo "Superuser rights required"
 exit 2
fi

genApacheConf(){
 echo -e "# Host ${HOME_DIR}$1/$2 :"
}

echo '"quoted"' | tr -d \" > text.txt
# The Greeter class
class Greeter
  def initialize(name)
    @name = name.capitalize
  end

  def salute
    puts "Hello #{@name}!"
  end
end

g = Greeter.new("world")
g.salute
@requires_authorization
def somefunc(param1='', param2=0):
    r'''A docstring'''
    if param1 > param2: # interesting
        print 'Gre\'ater'
    return (param2 - param1 + 1 + 0b10l) or None

class SomeClass:
    pass

>>> message = '''interpreter
... prompt'''

When the language is unknown or unspecified, code style is used:

foo bar baz

Tables

Tables are rendered as GUI tables (rather than as raw text) to ensure proper spacing.

FooBarBaz
Lorem ipsum30.0001
123
あいうえお-1e24>3.5

LaTeX fragments

Math in LaTeX markup is supported as both inline ($$ a^2 + b^2 $$) and block:

\begin{equation*} \oint∂ Σ \mathbf{B} ⋅ \mathrm{d}\boldsymbol{l} = μ_0 \left(\iintΣ \mathbf{J} ⋅ \mathrm{d}\mathbf{S} + ε_0 \frac{\mathrm{d}}{\mathrm{d}t} \iintΣ \mathbf{E} ⋅ \mathrm{d}\mathbf{S} \right) \end{equation*}

Prettified entities

Special characters written with syntax like \Omega or \leftrightarrow are shown with their “pretty” replacement characters: Ω ↔

Subscripts and superscripts are also prettified, and can contain entities and markup: H2O, A^*, e_(α^2 + 1)

Lists

When Reader Mode is enabled, list content is shown with content reflowed for easy reading on narrow screens.

Tap on list items with checkboxes to toggle them. Statistics cookies are updated automatically.

  • foo (complete: [%] / [/])
    • [ ] bar
      • [ ] car
      • [ ] dar
    • [ ] baz
      1. buzz
      2. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ipsum sapien, molestie nec posuere at, porta sit amet neque. Duis vulputate quis est et vestibulum. Quisque vehicula dolor vestibulum vestibulum porta.
    • bazinga
      thing
      this
      thang
      that

Drawers

Drawers are collapsed by default, but can be opened by touching the header.

Links

External links open in your web browser:

Links to other sections in the same document open in a narrowed view. See Narrowing.

Relative links to other Org Mode files are supported when Orgro has the required access permissions:

file:./orgro-manual-linked.org

The above link doesn’t require special permission because it points to a file bundled with Orgro. But your files will require permission; look for a banner at the top of a document prompting you to grant access.

For more details, including supported apps and OS restrictions, see the FAQ.

Image links are also supported; see Images.

Link abbreviations are supported if they are defined via #+LINK: lines: OrgroIssue:105

If a link matches a <<link target>> or a #+NAME: line then Orgro will jump to it. Try it out:

Radio targets

A <<<radio target>>> linkifies all occurrences of the word or phrase inside its brackets. Elsewhere in this document there is a radio target for abc123; tap to find it.

Emphasis

The default emphasis markers are supported:

  • bold
  • italic
  • underline
  • strikethrough
  • code
  • verbatim
  • nested /styles/ like *this*!

Hide the emphasis markers with Reader Mode.

Images

Images referenced by relative paths can be displayed when Orgro has the required access permissions:

./orgro-icon.png

The above image doesn’t require special permission because it is bundled with Orgro. But your images will require permission; look for a banner at the top of a document prompting you to grant access.

For more details, including supported apps and OS restrictions, see the FAQ.

Further, HTTP(S) links to images can be optionally loaded and displayed inline:

https://orgro.org/assets/appicon.png

Long touch an image to open it in a view where you can zoom and pan.

Images are cached on your device. To clear the cache and reset your choice if you chose Always or Never, see the action menu on the top screen.

Footnotes

Jump to named foonotes by touching a footnote reference.[fn:1]

Citations

Orgro can follow citations when a BibTeX bibliography has been specified like above[cite:@OrgroManual]. Touch a citation for details.

Attachments

Orgro can show attached images and open links to attached Org Mode files like so:

attachment:orgro-icon.png

attachment:orgro-manual-attachment.org

attachment:hello-world.pdf

attachment:orgro-app-store-promotion.mp4

Note that this depends on the ability to resolve relative links. See the Links section for details.

Encryption

Orgro recognizes encrypted content (OpenPGP/RFC 4880 messages starting with -----BEGIN PGP MESSAGE-----) and will offer to decrypt it. Only symmetrically (passphrase-only) encrypted messages can be decrypted.

If edited, decrypted content will be reencrypted with the same password on save. To make this possible, Orgro retains the password in memory until the document is closed. The password is not permanently stored anywhere.

Example

Horizontal rules

If you like to have a nice horizontal line in your document, you can do that:

Enjoy!

Other

Other syntaxes that are highlighted but not (yet) interpreted in any special way:

Timestamps and ranges
[2020-05-05 Tue]
Anonymous footnotes
guess what[fn:: this is an anonymous footnote]
Macro references
{{{date}}}

Editing

Some limited “structured” editing features are available:

  • Tap a list item with a checkbox to toggle the checkbox [/]
    • [ ] Try me!
    • [ ] And me!
  • Slide a section from right to left to cycle its TODO keyword
  • Tap a timestamp to edit with a date/time picker: [2024-11-07 Thu]

Statistics cookies are updated automatically when toggling checkboxes or cycling TODOs.

In addition, plain text editing is available from the floating edit button in the bottom right corner.

If Orgro has the appropriate permissions, it will save changes back to the original file. This is an experimental feature; see the FAQ for details.

If Orgro does not have the permissions it needs, it will prompt you to share the content of your file when you close it.

Edits can be undone and redone from the action menu.

Narrowing

Orgro can “narrow” the view to a specific section in two ways:

  • Open a link to a section
    • file:::#narrowing-section
    • file:::*Narrowing
    • id:2F5F32A8-5DB9-4FE7-BAAE-8BD328A73228
    • Even in other files:
      • file:orgro-manual-linked.org::#a-section
      • file:orgro-manual-linked.org::*Section
  • Long touch a section headline

Close the narrowed view by touching the Back button in the top app bar.

Reader Mode

Enable Reader Mode to reflow text, hide emphasis markers, and make meta lines (lines starting with #+) less prominent. The Reader Mode toggle can be found in one of two places:

Narrow screens (phones)
Reader mode in the action menu
Wide screens (tablets)
icon button in the top app bar

Visibility Cycling

Rotate sections between expanded and collapsed states just like Org Mode in Emacs:

  1. Overview: Show only top-level headlines
  2. Contents: Show all headlines of all levels, but no body text
  3. Show all: Show everything

Activate with the button in the top app bar.

Search

Touch the floating search button in the lower right of the screen. A search field will appear in the top app bar; enter your query here. Relevant sections will be expanded, while sections without hits will be collapsed. Hits are highlighted. Navigate hits with the up and down buttons in the lower right of the screen.

Sparse trees

Touch the floating search button in the lower right of the screen. An input bar will appear at the bottom of the screen above the keyboard with filter buttons:

Custom
Write an arbitrary sparse tree filter in a subset of the query language described in the Matching tags and properties section of the Org manual. See the FAQ for details on limitations.

Orgro will remember the last 10 custom filters. Long press the “Custom” button to directly apply a past filter.

Keywords
Filter by TODO, DONE, etc.
Priorities
Filter by section priority, e.g. A, B, C
Tags
Filter by section tags

Text Style

Adjust the text size and font.

Narrow screens (phones)
in the action menu
Wide screens (tablets)
icon button in the top app bar

Full screen width

On large screens, optionally let the document take up the entire screen width.

Questions and Feedback

Feel free to raise an issue on GitHub.

Examples

[fn:1] This is a footnote. Tap the reference here to jump back.

<<bizzbazz>> is a link target. You can link to it.

A #+NAME: line can also be linked to.

<<<abc123>>> is a radio target. Instances of abc123 throughout the document are linked here.

STARTUP keywords

Org Mode supports a variety of options for controlling the initial appearance of a document. These are specified with the #+STARTUP: keyword like so:

Options recognized by Orgro:

  • [no]hideblocks
  • [no]hidedrawers
  • hidestars / showstars
  • entitiespretty / entitiesplain
  • [no]inlineimages
  • [no]fold / overview / content / show[2..5]levels / showall / showeverything

TODO keywords

Org Mode allows customizing headline keywords (default: TODO, DONE). Orgro will interpret the #+TODO:, #+SEQ_TODO:, and #+TYP_TODO: keywords to inform:

  • What are valid keywords (invalid keywords are merely part of a section title)
  • What is the next state when cycling the keyword

Right-to-left scripts and bidi texts

Orgro supports right-to-left text layout:

من النهر إلى البحر / فلسطين ستتحرر

By default the direction for a paragraph is determined the same way as in Emacs: from the first strong directional character. To override this, you can set bidi-paragraph-direction to right-to-left or left-to-right in a local variables list.

Local Variables

Emacs allows defining a local variables list like below. Orgro can interpret the following settings from the local variables list:

org-entities-user
Specify additional entities for prettification. Syntax is the same as the “real” org-entities-user, but only name and utf-8 replacement are used:
  1. Name
  2. LaTeX replacement
  3. LaTeX mathp
  4. HTML replacement
  5. ASCII replacement
  6. Latin1 replacement
  7. utf-8 replacement

With the setting in this file, you can use e.g. \avocado to display \avocado.

org-entities-local
Same as org-entities-user but for use when you don’t want to overwrite your global org-entities-user value or include the entire value in your local variables. This is applied after the defaults and org-entities-user.
org-pretty-entities
Whether to prettify entities. Pretty entities are enabled by default; you can use this to disable them.
org-pretty-entities-include-sub-superscripts
Whether to prettify subscripts and superscripts. These are enabled by default; you can use this to disable them. Note that turning off org-pretty-entities will also disable subscripts and superscripts.
org-use-sub-superscripts
When subscripts and superscripts are enabled, setting this to the symbol {} requires brackets around subscripts and superscripts. In other words foo_bar will not render as a subscript but foo_{bar} will.
org-hide-emphasis-markers
Whether to hide emphasis markers. Emphasis markers are hidden in Reader Mode, but this allows hiding them outside of Reader Mode as well.
bidi-paragraph-direction
Override per-paragraph detection of text direction; see Right-to-left scripts and bidi texts.

To avoid having the local variables list show up in your exported docs, put it under a section with the COMMENT keyword or noexport tag.