Skip to content
This repository was archived by the owner on Oct 9, 2020. It is now read-only.

Hint Format

Jump to bottom
yaromir edited this page Apr 19, 2013 · 20 revisions

Обсуждение формата файла с хинтами

Формат должен быть одновременно относительно простым для машинной генерации ?и относительно человекочитаемым?.

По поводу человекочитаемости спорный вопрос: подразумевается ли, что кто-то будет вручную набирать хинты plain текстом? Если в плагин когда-нибудь будет добавлена возможность сохранения файла с хинтами - человекочитаемость самого формата не нужна.

Варианты:

  • JSON документ
  • XML

Пока склоняемся к JSON. Примерный формат:

{
    "targetCreated" : "",
    "targetModified" : "",
    "author" : "",
    "createdWith" : "",
    "hintsCreated": "",
    "hintsModified": "",
    "md5sum" : "",
    "hints": [
    {
        "tags": ["tag1", "tag2"],
        "text": "Ham! Spam! Spam! Spam! Eggs! Sausages!",
        "places": [ [0, 0, 0, 10], [10, 2, 20, 42] ]
    },
    {
        "tags": ["tag1", "tag2"],
        "text": "Dead parrot",
        "places": [ [3, 12, 3, 80] ]
    }
]
}

Обязательные поля:

  • targetCreated
  • targetModified
  • hintsCreated
  • hintsModified
  • md5sum
  • hints (Должен быть хотя бы один хинт?)

NB: Расширение файла-хинта - .hints; название файла-хинта должно совпадать с названием файла, к которому хинты относятся, включая его расширение, т.е. если документ называется dock.txt, то файл с его хинтами должен иметь название dock.txt.hints

Комментарии east825:

У меня есть следующие предложения касательно представления файла хинтов:

  • убрать ключ meta. Он кажется мне избыточным, проще все метаданные кидать прямо в корень. Таким образом в файле будут хинты (обязательная запись) и опциональная метаинформация.
  • кажется разумным не ограничивать облать хинта одним диапазоном. Например, рецензент может решить одно замечание отнести к нескольким местам в исходных текстах. Возможность использования нескольких курсоров в Sublime только этому способствует.
  • мне кажется, что диапазон можно представить как-нибудь попроще, например, списком из четырех целых чисел как [fromLine, fromCol, toLine, toCol]

Комментарии заказчика (ice-phoenix)

  • created- и modifiedTimestamp - это время создания и изменения оригинального файла, для которого были созданы хинты. Используются как еще один способ контроля целостности (а ля make).
  • Думаю, что имеет смысл сделать для хинтов такое понятие, как категория. Или, еще лучше, сделать возможность вешать тэги на отдельные хинты, чтобы потом фильтровать/удалять/работать с группами потэганных хинтов.

Некоторые комментарии к не совсем очевидным полям: createdWith - строка, описывающая версию ПО, которым был создан данный документ. sourceFileHash - хеш от исходного файла, для которого были созданы данные хинты. Нужен для обнаружения того, что файл изменился.

Вопросы:

Q:

  • Нужно предусмотреть расширяемость.

Q:

  • Как хранить timestamp?
    • Если обычный UNIX timestamp?
    • Если в человекочитаемой дате, то возникает множество проблем: порядок месяца и числа (американский формат: mm-dd-yyyy vs традиционный: dd-mm-yyyy), для сортировки может быть удобнее обратный формат: yyyy-mm-dd и т.п.

A:

Спасибо east825.

  • Хорошее предложение: хранить в ISO08601: yyyy-mm-dd:hh:mm:ss .

+:

  • Общепринятый стандарт.
  • От старшей единицы измерения к младшей - удобно сортировать, если понадобится.
  • Компромисс между человекочитаемостью и удобством манипулирования (например, той же сортировки).

Q:

  • Для случая, когда документ отредактирован и range больше не тот который нужен, хранить несколько строчек до и несколько строчек после участка в исходном тексте для восстановления позиции хинта в документе. (Как в diff. Спасибо east825 за идею.) ToDo Проработать более подробно, когда дело дойдет до редактирования.

Clone this wiki locally