cf020031308/agentdoc

A tiny agent which makes documents easy to be accessed, modified and searched.

Deprecated

For details please see The Reason I Created agentDoc and Why You Don't Need it In short, I found fzf and fasd powerful. There's no need to make another wheel unless for study purpose.

But if you still think agentDoc better in some ways, enjoy!

AGENTDOC 1 2020-06-23 1.6

NAME

agentDoc - An agent which makes documents easy to be accessed, modified and searched.

SYNOPSIS

agentDoc [.=]
agentDoc [PATTERN]
agentDoc [+-] [DOCNAME]
agentDoc [SOURCE | DOCNAME] [DESTINATION | DOCNAME]

COMMANDS

agentDoc
    review the most unread doc
agentDoc .
    list all docs
agentDoc + docname
    create a doc to edit
agentDoc - docname
    delete a doc
agentDoc pattern
    search a doc to edit
agentDoc URL/filepath1/docname1 filepath2/docname2
    append a page/file/doc to an internal doc or an external file
agentDoc URL/filepath1/docname1 dirpath
    export a page/file/doc to a directory
agentDoc = [comment]
    sync with git
agentDoc -h
    help

About Default Doc

agentDoc guesses the filename if not provided.

When the managed folder is synced with Github Wiki, the default filename is 'home'.
When the managed folder is a git repository, the default filename is 'readme'.

About Review

When agentDoc is called without any arguments, it searches through the managed directory for the most unread document and open it.

With this feature you may recurrently review your documents and

• remember everything in your knowledge base
• keep your notes neat and useful

The score to evaluate how 'unread' a document is = ((now - last_access_time) / (1 + last_access_time - last_change_time) - 1) * doc_size

If all the scores are less than 0, another score0 = (now - last_access_time) / (1 + last_access_time - last_change_time) is used.

About Search

When searching, agentDoc looks at the filenames and contents to pick the only file with its name or content exactly or partially matching the pattern, then opens it for editing.

In every search phase if the result contains multiple files, agentDoc prints them and quit immediately.

INSTALLATION

curl "https://raw.githubusercontent.com/cf020031308/agentDoc/master/agentDoc" -o /usr/local/bin/agentDoc
chmod 755 /usr/local/bin/agentDoc

Put or link agentDoc as a copy into the folder where you hope to manage documents. Then name the copy as the extension of the managed documents, such as md or txt. It can also be hidden by being named as .md, .txt, etc.

And It's recommended to link the copy into $path such as /usr/local/bin/agentDoc to make it convenient to use.

Installation Examples

ln -sf agentDoc /Documents/cheatsheet/.md
ln -sf /Document/cheatsheet/md /usr/local/bin/cheat
Manage cheatsheet in markdown format with command cheat

cp agentDoc /Documents/myproject.wiki.git/md
ln -sf /Document/myproject.wiki.git/md /usr/local/bin/wk
Manage documents of github wiki in markdown format with command wk

ln -sf agentDoc ~/.vim/snippets/snippets
ln -sf ~/.vim/snippets/snippets /usr/local/bin/snippets
Manage vim-snippets with command snippets

Usecases

With different extensions and aliases agentDoc becomes:

1. Shortcut
2. Todo app
3. Cheatsheet
4. Snippet manager
5. Wiki, blog, diary, ...
6. ...

SPECIALITIES

agentDoc leverages the power of Github https://github.com and markdown https://guides.github.com/features/mastering-markdown/.

1. Properly fix referenced URLs when getting a remote markdown file
2. Automatically manage images referenced in a local markdown file
   1. When editing, you can reference an image relative to your working directory (PWD);
   2. When appending, images referenced in the source file will be copied to the destination folder, and links converted as well.
   3. When syncing, images in the managed folder which are not referenced will be removed before pushing.
3. Friendly with Github
   1. URLs of raw. When getting a remote file from Github or Github Wiki, agentDoc guesses the URL of the raw file according to the given URL.
   2. Issue links. When getting a remote file from Github, GFM Issue links will be converted to normal links.

EXIT STATUS

The agentDoc utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

git(1), curl(1)

AUTHOR

Written first in May, 2018 by Roy https://github.com/cf020031308/agentDoc
Distributed under the terms of the BSD license.

agentdoc's Issues

Smarter default filename

• when dealing with markdown for github wiki the default name is 'home'
• when dealing with markdown for github the default name is 'readme'

Fix Full-wdith Code

Convert ！【百度】（https://www.baidu.com) to ![百度](https://www.baidu.com) after editing.

installation shortcut

e.g. agentDoc ./.md /usr/loca/bin/wi

Version 2

# Common Commands
agentDoc [filename pattern] [op] [args]
# # search
agentDoc [filename pattern] / [content pattern]
# # create then push and print
echo "blah blah" | agentDoc [filename pattern] +[n]
agentDoc [filename pattern] +[n] "blah blah"
mdmv file | agentDoc [filename pattern] +[n]
# # pop till remove
agentDoc [filename pattern] -[n] [content pattern]
# # move
agentDoc [filename pattern] [output]
# # # remove: search to clear with editor and then pop till remove
# # # remove and print
agentDoc [filename pattern] /dev/stdout
# # # silent remove
agentDoc [filename pattern] /dev/null

# Shortcuts
# # edit the default or only file, if none, print help
agentDoc
# # search to edit
agentDoc [pattern]

# Additional Commands
# # install
agentDoc : install /usr/local/bin/wk ~/workplace/cf020031308.github.io/wiki/.md
# # sync
agentDoc : gitsync [message]
# # reference
agentDoc [file pattern] : mdref [ref files]
## help
agentDoc -h
## other
agentDoc [file pattern] : mdmv /dev/null

#1
#2

mdcp

mdcp [src] [dst]

move markdown files around while keeping links and references acessable.

Bug in URL convertion

for example, See also [sed scripts](#sed-scripts) section for an alternate way. is converted to https://github.com/learnbyexample/Command-line-text-processing/raw/master/#sed-scripts and this is wrong.

Extract markdown processing as an triggered extension

The core ability of agentDoc should be "making documents easy to be accessed and searched". So it's better to extract all the code related to markdown out of the main logic and make it a somewhat trigger activated by the extension "md" or "markdown". Likewise it will be easy to add other triggers to process other file types such as "txt", "snippets", ...

link references automatically

Toggle the links: agendDoc $ docname

Output:

Links added/removed:
+ [幕布](https://mubu.com/inv/2337342)
+ [How to Publish](How-to-publish.md) 

If txt are all lowercased, ignore cases.

Always check first if there are links that can be added.
If none, remove links.

DO NOT convert txt in codes

situation 1: affiliate links

Read configs from an external file such as $.md (so it can also be managed)

- [幕布](https://mubu.com/inv/2337342)

Replace all the unlinked "幕布" to [幕布](https://mubu.com/inv/2337342)

situation 2: related docs

Read the first lines of all managed docs and link them with the file path (trim .$ext when dealing with github-wiki).

Turn it off before exporting.