Элегантная аннотация кода для учебников?

Question

Я писал некоторые учебные пособия и пытаюсь найти элегантный способ добавления построчных аннотаций к коду в учебных пособиях.

Например, предположим, у меня есть такой код:

<h1>Demo of web page</h1>
<p>This is a paragraph</p>

Я хотел бы иметь возможность добавить что-то (возможно, всплывающую подсказку или какой-нибудь эффект лайтбокса), которое позволит мне представить читателю объяснение каждой строки, в то же время позволяя им видеть строку в контексте. Лучшее, что я смог придумать, - это прозаические объяснения, в которых говорится что-то вроде «Строка, начинающаяся с <h1>, является заголовком».

Кто-нибудь когда-нибудь видел что-то подобное?

Answer 1

Вы можете проверить docco:

http://jashkenas.github.com/docco/

Он написан на CoffeeScript и генерирует HTML-документ из исходного файла, разделяя разделы комментариев и код. Он устанавливает комментарии как аннотации для каждого раздела в одном столбце и соответствующий правильно выделенный код в другом столбце. Я думаю, что это отличный простой способ получить аннотации, сохраняя код в контексте. О, и это также знает уценку.

Answer 2

Старый, но хороший вопрос, я искал похожие вещи, когда нашел это.Есть множество способов сделать аннотацию HTML, см. Эту статью для очень хорошего списка и объяснений .

Если вы хотите аннотацию, которая просто говорит пользователю, что делает каждая строка, я бы написалHTML-комментарии для небольших фрагментов кода и большие внешние аннотации для больших объемов кода.Затем вы можете проанализировать их, используя пользовательский JS, чтобы показать более симпатичные поля, если хотите.

<h1>Heading</h1> <!-- A heading element -->
<p>paragraph</p> <!-- A paragraph element -->
<p>Paragraph with
    <b>Bold</b>      <!-- An inline Bold element -->
text</p>

Для больших объемов кода я бы рассмотрел использование чего-то вроде документации, создаваемой Docco .Конечно, это для JavaScript, но кто говорит, что подобное не может быть сделано для HTML.Поскольку это было помечено с помощью jquery-UI, вас также может заинтересовать текстовый аннотатор jQuery .

Answer 3

Я думаю, я мог бы найти что-то, что могло бы соперничать с Docco: функция всплывающего окна в Twitter Bootstrap: http://twitter.github.com/bootstrap/javascript.html#popover

Я не уверен, что это на самом деле будет хорошо выглядеть, но это похоже на хорошее начало.

Answer 4

А как насчет использования атрибутов заголовка?

<h1 title="your hover text">your text</h1>