[go: up one dir, main page]

Improve command naming for better intuitiveness and alignment with zk-nvim

Problem

The current command names are not intuitive and don't align well with zk-nvim's naming conventions. Several commands have cryptic suffixes or unclear purposes from their names alone.

Current Commands and Issues

Commands Needing Renaming:

  1. :ZkNewTitleT and :ZkNewContentT

    • Issue: The "T" suffix is cryptic and unclear
    • Proposed: :ZkNewFromTitleSelection:ZkNewFromTitleSelectionWithTemplate (too long) OR better: :ZkNewFromTitle and keep zk-nvim's as-is
    • Alternative: Make template selection a feature of existing commands via options
  2. :ZkInsertSnippet

    • Current: Clear but could align better with zk-nvim patterns
    • Proposed: Keep as-is (actually good name)
  3. :ZkRemove and :ZkRemovePick

    • Issue: "Remove" is ambiguous - could mean unlink/delete/archive
    • Proposed: :ZkDelete and :ZkDeletePick OR :ZkTrash and :ZkTrashPick
  4. :ZkNewFromTemplate

    • Issue: Redundant with :ZkNew which already accepts a template parameter
    • Proposed: Remove command, document using :ZkNew { template = "name" } instead
    • Alternative: Keep as convenience command but rename to :ZkPickTemplate
  5. :ZkSlides

    • Issue: Unclear what this does (present? create? export?)
    • Proposed: :ZkPresent or :ZkPresentSlides
  6. :ZkUpdate

    • Current: Aligns well with zk CLI (zk update)
    • Proposed: Keep as-is (good name)
  7. Integration Commands (:ZkOrphans, :ZkRecents, :ZkPinned, :ZkHub, :ZkLast)

    • Current: Clear and intuitive
    • Proposed: Keep as-is (good names)

Recommended Changes

High Priority (Breaking Changes):

ZkNewTitleT        → ZkNewFromTitle             (shorter, clearer)
ZkNewContentT      → ZkNewFromContent           (shorter, clearer)
ZkRemove           → ZkDelete                   (more explicit)
ZkRemovePick       → ZkDeletePick               (more explicit)
ZkSlides           → ZkPresent                  (clearer purpose)

Medium Priority (Consider):

ZkNewFromTemplate  → ZkPickTemplate             (or remove entirely)
ZkInsertSnippet    → ZkSnippet                  (shorter, still clear)

Keep As-Is:

ZkUpdate           ✓ (aligns with zk CLI)
ZkOrphans          ✓ (clear and intuitive)
ZkRecents          ✓ (clear and intuitive)
ZkPinned           ✓ (clear and intuitive)
ZkHub              ✓ (clear and intuitive)
ZkLast             ✓ (clear and intuitive)

Implementation Considerations

  1. Backward Compatibility: Create deprecated aliases for old commands
  2. Documentation: Update all docs with new names
  3. Migration Guide: Provide clear migration path for users
  4. Config Keys: Update config keys to match new names

zk-nvim Command Pattern Reference

For comparison, zk-nvim uses these patterns:

  • Zk + Action (ZkNew, ZkIndex, ZkCd)
  • Zk + Action + Target (ZkInsertLink, ZkNewFromTitleSelection)
  • Zk + Noun (ZkNotes, ZkTags, ZkBacklinks, ZkLinks)

We should follow similar patterns for consistency.

Proposed Config Structure After Rename

require('zk-extras').setup({
  commands = {
    ZkDelete = true,                    -- was ZkRemove
    ZkDeletePick = true,                -- was ZkRemovePick
    ZkSnippet = true,                   -- was ZkInsertSnippet
    ZkPickTemplate = true,              -- was ZkNewFromTemplate
    ZkNewFromTitle = true,              -- was ZkNewTitleT
    ZkNewFromContent = true,            -- was ZkNewContentT
    ZkPresent = true,                   -- was ZkSlides
    ZkUpdate = true,
    ZkIntegration = true,               -- ZkOrphans, ZkRecents, etc.
  }
})