Page MenuHomePhabricator

update outdated links related to UAHF and use explicit MarkDown syntax
ClosedPublic

Authored by PiRK on Sep 18 2020, 15:10.

Details

Reviewers
jasonbcox
Group Reviewers
Restricted Owners Package(Owns No Changed Paths)
Restricted Project
Commits
rABC5bc64bce59f3: update outdated links related to UAHF and use explicit MarkDown syntax
Summary

Some links in doc/abc/*md point toward a github repository that no longer exists. They have been updated to point to the local md file. Additionaly, some MarkDown syntax has been added to make links work on the HTML version auto-generatedfor bitcoinabc.org

Test Plan
SRC_DIR="/home/pierre/git/bitcoin-abc"
TOPLEVEL="/home/pierre/git/bitcoin-abc-website"
pushd "${SRC_DIR}"
ABC_MD_DOCS_BASE="${TOPLEVEL}/abc_md_docs"
mkdir -p "${ABC_MD_DOCS_BASE}"
FILES=($(git ls-files "*.md"))
for FILE in "${FILES[@]}"
do
  FILE_DST="${ABC_MD_DOCS_BASE}/${FILE}"
  mkdir -p "$(dirname ${FILE_DST})"

  NAME="${FILE}" \
  PERMALINK="/${FILE%.*}.html" \
  envsubst < "${TOPLEVEL}/scripts/md_docs_frontmatter.yml.in" > "${FILE_DST}"
  cat "${FILE}" >> "${FILE_DST}"
done
popd

Then test the links by running:

bundle exec jekyll serve

Diff Detail

Event Timeline

Owners added a reviewer: Restricted Owners Package.Sep 18 2020, 15:10
PiRK requested review of this revision.Sep 18 2020, 15:10
jasonbcox requested changes to this revision.Sep 18 2020, 18:52
jasonbcox added a subscriber: jasonbcox.

I noticed your test plan is rather complex and duplicates a lot of the logic in scripts/fetch_documentation.sh in the website repo. Consider improving it so it can take a local target instead of always pulling from the internet. This should come in a separate diff of course.

doc/abc/replay-protected-sighash.md
205

Are these <a> tags necessary? It looks like you can replace all of them with [name](url) syntax.

This revision now requires changes to proceed.Sep 18 2020, 18:52

So far I have not been able to find another way of adding internal references to arbitrary places in a markdown file without using <a name="..."></a>. For instance the reference defined on line 199 is linked-to on line 9 with BIP143[[1]](#bip143)

The simplest solution would be to get rid completely of the References section. It seems to be the only documentation file using a reference section rather than adding links directly where they are needed.

EDIT: I just understood that inline comments are posted only after adding a comment. I was wondering why I could not directly reply to inline comments.

doc/abc/replay-protected-sighash.md
205

So far I have not been able to find another way of adding internal references to arbitrary places in a markdown file without using <a name="..."></a>. For instance the reference defined on line 199 is linked-to on line 9 with BIP143[[1]](#bip143)

The simplest solution would be to get rid completely of the References section, and add the links directly where they are needed.

Put links directly in the text and remove References section

I noticed your test plan is rather complex and duplicates a lot of the logic in scripts/fetch_documentation.sh in the website repo. Consider improving it so it can take a local target instead of always pulling from the internet.

I thought about it earlier today. I will look into it tomorrow.

jasonbcox added inline comments.
doc/abc/replay-protected-sighash.md
205

Headers like ### automatically add anchors: https://www.bitcoinabc.org/doc/abc/replay-protected-sighash.html#references
Considering this anchor is at the bottom of the page, it doesn't really matter where you anchor to exactly, so you could #references and it would work all the same.

But I think linking directly to the doc itself is better. One less click.

This revision is now accepted and ready to land.Sep 18 2020, 20:12