Запуск Apple DocC как файла справки Apple
С появлением DocC для создания документации из исходного кода, можно ли взять вывод DocC и использовать его в качестве источника правды для справочной книги Apple (для использования внутри приложения macOS)?
- Введение в DocC: https://developer.apple.com/videos/play/wwdc2021/10166/
- Справочная книга Apple для приложений Mac: https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CHH206-CIHCIH
2 ответа
Возможно нет. Это совершенно разные животные. Справочная книга - это полный веб-сайт с некоторой помощью для определенных типов якорей. DocC - это строго ограниченное формализованное представление очень определенного типа информации. В самом деле, даже если вы соедините эти две вещи, вы не захотите; справочная книга помогает пользователям, тогда как DocC отображает программный API для программиста.
В качестве примера приведу справочную книгу, которую я написал:
http://www.apeth.com/sd5help/index.html
Вы не могли бы выразить это с помощью DocC. Если проблема в том, что вы ищете инструмент, который поможет вам писать справочные книги, DocC - не то.
Можно ли взять вывод DocC и использовать его как источник истины для справочной книги Apple?
- Да, но, скорее всего, не стоит .
@matt упомянул:
DocC - это строго ограниченное формализованное представление очень определенного типа информации.
Однако я не согласен с этим. Вы можете создавать страницы статей с помощью DocC: Getting Started with Sloths
Эти проблемы с использованием DOCC для создания Apple , справки Book:
Документация DocC поддерживает только базовый синтаксис уценки, поэтому возможности форматирования ограничены.
DocC экспортирует документацию как одностраничное веб-приложение, где Apple Help Book ожидает отдельные файлы html для каждой страницы справки. Таким образом, вам нужно будет автоматически создавать статические файлы HTML.
Документация DocC не позволяет добавлять пользовательские метатеги для индексации или ключевые слова и имена для якорей. (Возможно, вы можете использовать комментарии в уценке, а затем автоматически генерировать их из комментариев. Однако я не уверен, останутся ли комментарии в уценке в файле, созданном DocC)
Вам все равно потребуется использовать Help Indexer для их индексации.
@matt упомянул:
Справочная книга помогает пользователям, тогда как DocC отображает программный API для программиста.
Вы определенно можете объединить эти два и использовать файлы, сгенерированные DocC, в качестве источника истины, но я бы предпочел сделать это с другими редакторами HTML или лучшим редактором уценки, если вы предпочитаете синтаксис уценки.