Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add support for using existing Dash.app docsets #53

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

add support for using existing Dash.app docsets #53

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1f9d853
add support for using existing Dash.app docsets
smackesey Oct 26, 2020
a992bec
ensure Dash.app docsets are extracted
smackesey Oct 27, 2020
a5bac0d
fix sunaku requests
smackesey Nov 15, 2020
83e2a6f
Update manpages
smackesey Nov 20, 2020
be94464
Extract Dash unpacking to dasht-docsets-inherit
smackesey Jul 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ which aptly characterizes the terminal environment where everything is text.

* Keep [Dash] docsets anywhere you like.

* Access existing docset library managed by Dash.app (MacOS only).

### Preview

Watch the "[dasht in a terminal](https://vimeo.com/159462598)"
Expand Down Expand Up @@ -61,6 +63,8 @@ Optional:

* [gawk] for dasht-server(1) search engine

* [Dash] to let the Dash MacOS app manage your docsets

Development:

[binman]: https://sunaku.github.io/binman/
Expand Down Expand Up @@ -91,6 +95,15 @@ Manually, on any system:

export MANPATH=location_where_you_cloned_or_downloaded_dasht/man:$MANPATH

### Dash.app integration

Set `DASHT_USE_DASH_APP=true` to use the docsets stored by Dash.app on your
machine. This makes `dasht` act like a read-only client for your Dash.app
docset library-- all docset management commands (`install`, `update`, `remove`)
are disabled. This also provides access to an expanded library of docsets,
because currently `dasht` can only download and/or build a subset of the
docsets available through Dash.app.

### Vim integration

Use the [vim-dasht](https://github.com/sunaku/vim-dasht) plugin for (Neo)Vim.
Expand Down Expand Up @@ -142,6 +155,11 @@ which defines the filesystem location where download links are cached.
If undefined, its value is assumed to be `$XDG_CACHE_HOME/dasht/`
or, if `XDG_CACHE_HOME` is also undefined, `$HOME/.cache/dasht/`.

Set `DASHT_USE_DASH_APP=true` to enable Dash.app integration (MacOS only). See
[Dash.app integration](#dashapp-integration) for details. Note that this will
also change the default setting of `DASHT_DOCSETS_DIR` to `~/Libary/Application
Support/Dash` (where Dash.app docsets are stored by default).

## Development

If you make changes to the embedded manual pages found in the comment headers
Expand Down
23 changes: 23 additions & 0 deletions bin/dasht
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 44
Expand All @@ -67,11 +72,29 @@
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_USE_DASH_APP:=false}
if $DASHT_USE_DASH_APP; then
: ${DASHT_DOCSETS_DIR:="$HOME/Library/Application Support/Dash"}
else
: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
fi

if test $# -gt 0; then
pattern=$1
shift
fi

# Ensure any docsets we are accessing from the Dash.app library have had their
# documents extracted. Dash.app leaves the documents in the tarball by default.
if $DASHT_USE_DASH_APP; then
dasht-docsets "$@" | while read docset; do
root=("$DASHT_DOCSETS_DIR/"*/*"/${docset}.docset")
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't need ( array ) syntax.

Copy link
Owner

@sunaku sunaku Jul 21, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding your comment:

those particular globs won't expand in my bash v3.2.57 without the array syntax. Something about putting an * next to a quote, I think.

Could you please try surrounding the stars with slashes (by moving them out of the surrounding strings)? Like this:

root="$DASHT_DOCSETS_DIR"/*/*/"$docset".docset

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, if BASH is requiring you to add ( array ) syntax because the glob can potentially match more than one file, then it would be better to convert this expression into a nested loop:

for root in "$DASHT_DOCSETS_DIR"/*/*/"$docset".docset; do
  # ...
done

if ! test -d "${root}/Contents/Resources/Documents"; then
dasht-docsets-extract "$root/Contents/Resources/tarix.tgz"
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this extraction would better fit in a different script, say dasht-docsets-inherit, which would focus on preparing docsets from other apps for use with dasht. This way, the dasht script won't exceed its original purpose.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I made the requested changes and tested it out a bit, I think all is working well. BTW, you should update gitignore and instructions re manpages:

  • /man is in gitignore despite being included in the repo
  • I am not familiar with binman-rake, but I think it's behavior changed since you posted the instructions. I ran it and it generated a bunch of html, markdown, and a CSS flie. I deleted all of the excess files it generated and just included the changes to the manpage-format one and the dasht-docsets-inherit.

Copy link
Owner

@sunaku sunaku Jul 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your feedback. Actually, both of those are exactly as they're meant to be:

  • For gitignore, /man is ignored (line 2) but some of its contents aren't (line 1). 🤓
  • For binman-rake, the excess files it generates are ignored by gitignore line 2.
!/man/man?/*.?
/man

fi
done
fi

count=$(dasht-docsets "$@" | wc -l)
if test $count -eq 0; then
# notify user when no docsets are installed so they can go install them
Expand Down
22 changes: 20 additions & 2 deletions bin/dasht-docsets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## SEE ALSO
#
# dasht-docsets-install(1), dasht-docsets-update(1), dasht-docsets-remove(1),
Expand All @@ -46,9 +51,22 @@
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_USE_DASH_APP:=false}
if $DASHT_USE_DASH_APP; then
: ${DASHT_DOCSETS_DIR:="$HOME/Library/Application Support/Dash"}
else
: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
fi

ls "$DASHT_DOCSETS_DIR" |
{
if $DASHT_USE_DASH_APP; then
for x in "$DASHT_DOCSETS_DIR"/*/*/*.docset; do
basename "$x"
done
else
ls "$DASHT_DOCSETS_DIR"
fi
} |
sed -n 's/\.docset$//p' |
sort -u |
grep -E -i "$(IFS='|'; echo "$*")"
30 changes: 29 additions & 1 deletion bin/dasht-docsets-extract
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,16 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 46
# Command was not executed because `DASHT_USE_DASH_APP` is set.
#
# ## SEE ALSO
#
# dasht-docsets-install(1), dasht-docsets-update(1), [Dash]
Expand All @@ -50,10 +60,28 @@
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_USE_DASH_APP:=false}
if $DASHT_USE_DASH_APP; then
: ${DASHT_DOCSETS_DIR:="$HOME/Library/Application Support/Dash"}
else
: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
fi

test $# -gt 0
for tgz; do

# Extract Documents dir inside existing Dash.app docset directory. Dash.app
# leaves the Documents inside the tarball tarix.tgz by default.
if $DASHT_USE_DASH_APP; then
pushd "$(dirname "$tgz")" >/dev/null
docset_name="$(basename "${tgz%/*/*/*}")"
tar -x -f "$tgz" "$docset_name/Contents/Resources/Documents"
mv "$docset_name/Contents/Resources/Documents" .
rm -r "$docset_name"
popd >/dev/null
continue
fi

want="$DASHT_DOCSETS_DIR/$(basename "$tgz" .tgz).docset"
have="$DASHT_DOCSETS_DIR/$(tar -t -f "$tgz" -z | head -1 | sed 's|/.*||')"

Expand Down
17 changes: 17 additions & 0 deletions bin/dasht-docsets-install
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,16 @@
# If undefined, its value is assumed to be `$XDG_CACHE_HOME/dasht/`
# or, if `XDG_CACHE_HOME` is also undefined, `$HOME/.cache/dasht/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 46
# Command was not executed because `DASHT_USE_DASH_APP` is set.
#
# ## SEE ALSO
#
# dasht-docsets-extract(1), dasht-docsets-update(1), dasht-docsets-remove(1),
Expand All @@ -58,6 +68,13 @@

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_CACHE_DIR:=${XDG_CACHE_HOME:-$HOME/.cache}/dasht}
: ${DASHT_USE_DASH_APP:=false}

if $DASHT_USE_DASH_APP; then
echo "extract, install, remove, and update operations are disabled when \
DASHT_USE_DASH_APP=true." >&2
exit 46
fi

test "$1" = '-f' -o "$1" = '--force' && force=1 && shift || unset force

Expand Down
19 changes: 19 additions & 0 deletions bin/dasht-docsets-remove
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,16 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 46
# Command was not executed because `DASHT_USE_DASH_APP` is set.
#
# ## SEE ALSO
#
# dasht-docsets-install(1), dasht-docsets-update(1), dasht-docsets(1), [Dash]
Expand All @@ -50,6 +60,15 @@
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_USE_DASH_APP:=false}

if $DASHT_USE_DASH_APP; then
echo "extract, install, remove, and update operations are disabled when \
DASHT_USE_DASH_APP=true." >&2
exit 46
fi

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}

test "$1" = '-f' -o "$1" = '--force' && force=1 && shift || unset force
Expand Down
17 changes: 17 additions & 0 deletions bin/dasht-docsets-update
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,16 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 46
# Command was not executed because `DASHT_USE_DASH_APP` is set.
#
# ## SEE ALSO
#
# dasht-docsets-extract(1), dasht-docsets-install(1), dasht-docsets-remove(1),
Expand All @@ -46,6 +56,13 @@
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_USE_DASH_APP:=false}

if $DASHT_USE_DASH_APP; then
echo "extract, install, remove, and update operations are disabled when \
DASHT_USE_DASH_APP=true." >&2
exit 46
fi

dasht-docsets "$@" | while read -r docset; do
ls "$DASHT_DOCSETS_DIR/$docset"*.tgz
Expand Down
5 changes: 5 additions & 0 deletions bin/dasht-query-html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 44
Expand Down
19 changes: 17 additions & 2 deletions bin/dasht-query-line
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## EXIT STATUS
#
# 44
Expand All @@ -86,7 +91,12 @@
# Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
# Distributed under the terms of the ISC license (refer to README file).

: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
: ${DASHT_USE_DASH_APP:=false}
if $DASHT_USE_DASH_APP; then
: ${DASHT_DOCSETS_DIR:="$HOME/Library/Application Support/Dash"}
else
: ${DASHT_DOCSETS_DIR:=${XDG_DATA_HOME:-$HOME/.local/share}/dasht/docsets}
fi

pattern=$(echo " $1 " | sed -e 's/[%_]/\\&/g' -e 's/[[:space:]]\{1,\}/%/g')
test $# -gt 0 && shift # shift off PATTERN so argv contains solely DOCSETs
Expand All @@ -95,7 +105,12 @@ status=44 # (default) exit with a nonzero status when no results are found
trap 'status=0' USR1 # override default exit status when results are found

dasht-docsets "$@" | while read -r docset; do
database="$DASHT_DOCSETS_DIR/$docset".docset/Contents/Resources/docSet.dsidx
if $DASHT_USE_DASH_APP; then
relpath=("$DASHT_DOCSETS_DIR"/*/*/"$docset".docset)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the ( array ) notation? Should be removed.

database="$relpath/Contents/Resources/docSet.dsidx"
else
database="$DASHT_DOCSETS_DIR/$docset".docset/Contents/Resources/docSet.dsidx
fi
file_url="file://$(dirname "$database")/Documents/"

dasht-query-exec "$pattern" "$database" -line |
Expand Down
5 changes: 5 additions & 0 deletions bin/dasht-server
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## SEE ALSO
#
# socat(1), dasht-server-http(1), dasht-docsets(1), dasht(1), [Dash]
Expand Down
5 changes: 5 additions & 0 deletions bin/dasht-server-http
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,11 @@
# If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
# or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
#
# `DASHT_USE_DASH_APP`
# Set to "true" to use Dash.app's (MacOS only) docset library. Disables
# docset management commands (install, remove, update). Also changes the
# default `DASHT_DOCSETS_DIR` to "~/Library/Application Support/Dash".
#
# ## SEE ALSO
#
# dasht-query-html(1), dasht-server(1), dasht-docsets(1), dasht(1), [Dash]
Expand Down
9 changes: 9 additions & 0 deletions man/man1/dasht-docsets-extract.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,15 @@ If an extracted directory already exists, its contents are updated in place.
Defines the filesystem location where your Dash \[la]https://kapeli.com/dash\[ra] docsets are installed.
If undefined, its value is assumed to be \fB\fC$XDG_DATA_HOME/dasht/docsets/\fR
or, if \fB\fCXDG_DATA_HOME\fR is undefined, \fB\fC$HOME/.local/share/dasht/docsets/\fR\&.
.TP
\fB\fCDASHT_USE_DASH_APP\fR
Set to "true" to use Dash.app's (MacOS only) docset library. Disables
docset management commands (install, remove, update). Also changes the
default \fB\fCDASHT_DOCSETS_DIR\fR to "~/Library/Application Support/Dash".
.SH EXIT STATUS
.TP
46
Command was not executed because \fB\fCDASHT_USE_DASH_APP\fR is set.
.SH SEE ALSO
.PP
.BR dasht-docsets-install (1),
Expand Down
9 changes: 9 additions & 0 deletions man/man1/dasht-docsets-install.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,15 @@ or, if \fB\fCXDG_DATA_HOME\fR is undefined, \fB\fC$HOME/.local/share/dasht/docse
Defines the filesystem location where download links are cached.
If undefined, its value is assumed to be \fB\fC$XDG_CACHE_HOME/dasht/\fR
or, if \fB\fCXDG_CACHE_HOME\fR is also undefined, \fB\fC$HOME/.cache/dasht/\fR\&.
.TP
\fB\fCDASHT_USE_DASH_APP\fR
Set to "true" to use Dash.app's (MacOS only) docset library. Disables
docset management commands (install, remove, update). Also changes the
default \fB\fCDASHT_DOCSETS_DIR\fR to "~/Library/Application Support/Dash".
.SH EXIT STATUS
.TP
46
Command was not executed because \fB\fCDASHT_USE_DASH_APP\fR is set.
.SH SEE ALSO
.PP
.BR dasht-docsets-extract (1),
Expand Down
9 changes: 9 additions & 0 deletions man/man1/dasht-docsets-remove.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@ Forces the operation by overriding the interactive confirmation prompt.
Defines the filesystem location where your Dash \[la]https://kapeli.com/dash\[ra] docsets are installed.
If undefined, its value is assumed to be \fB\fC$XDG_DATA_HOME/dasht/docsets/\fR
or, if \fB\fCXDG_DATA_HOME\fR is undefined, \fB\fC$HOME/.local/share/dasht/docsets/\fR\&.
.TP
\fB\fCDASHT_USE_DASH_APP\fR
Set to "true" to use Dash.app's (MacOS only) docset library. Disables
docset management commands (install, remove, update). Also changes the
default \fB\fCDASHT_DOCSETS_DIR\fR to "~/Library/Application Support/Dash".
.SH EXIT STATUS
.TP
46
Command was not executed because \fB\fCDASHT_USE_DASH_APP\fR is set.
.SH SEE ALSO
.PP
.BR dasht-docsets-install (1),
Expand Down
Loading