<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en" style='--code-editor-font: var(--default-mono-font, "GitLab Mono"), JetBrains Mono, Menlo, DejaVu Sans Mono, Liberation Mono, Consolas, Ubuntu Mono, Courier New, andale mono, lucida console, monospace;'>
<head>
<meta content="text/html; charset=US-ASCII" http-equiv="Content-Type">
<title>
GitLab
</title>
<style data-premailer="ignore" type="text/css">
a { color: #1068bf; }
</style>
<style>img {
max-width: 100%; height: auto;
}
body {
font-size: .875rem;
}
body {
-webkit-text-shadow: rgba(255,255,255,.01) 0 0 1px;
}
body {
font-family: "GitLab Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; font-size: inherit;
}
</style>
</head>
<body style='font-size: inherit; -webkit-text-shadow: rgba(255,255,255,.01) 0 0 1px; font-family: "GitLab Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";'>
<div class="content">
<p style="color: #777777;">
<a href="https://gitlab.rtems.org/frank_k">Frank Kuehndel</a>
<a href="https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/94#note_120511">commented</a>:
</p>
<div class="md" style="position: relative; z-index: 1; color: #28272d; word-wrap: break-word;">
<p dir="auto" style="color: #28272d; margin: 0 0 16px;" align="initial"><a href="https://gitlab.rtems.org/amar" data-reference-type="user" data-user="2" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Amar Takhar" style="color: #0b5cad; background-color: #cbe2f9; border-radius: .25rem; margin-top: 0; padding: 0 2px;">@amar</a> I have absolutely no time left for the next three maybe six months. I dislike to make suggestions when I cannot provide any help realizing them. Since you asked, a few points (which may not be in line with anybody else):</p>
<ul dir="auto" style="text-align: initial; list-style-type: disc; margin: 0; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">
<p style="color: #28272d; margin: 0 0 16px;">One could split the README:</p>
<ul style="list-style-type: circle; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The parts about "Documentation Standard", "Images" and Restructured Text (from "Introduction") could go into the RTEMS Engineering Manual (e.g. section "6.4 Documentation Guidelines")</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The part on how to build the documentation (e.g. Dockerfile) and how to configure the build (current section "Building") could go into the RTEMS User Manual.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The rest (such as old information about building documentation on different OS) could stay in the README together with links to the above mentioned parts.</li>
</ul>
</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">
<p style="color: #28272d; margin: 0 0 16px;">For the part on how to build the documentation (e.g. in the Users Manual), I would only provide a Dockerfile plus the info which is currently in section "Building". Most of the information about LaTeX, Sphinx, npm, etc. is mostly implicitly covered by a Dockerfile.</p>
<ul style="list-style-type: circle; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">I think it would be better to use Ubuntu as OS for a Dockerfile. It is more common than OpenSUSE. Fedora may be an option if you think this makes a difference in documentation quality. I am happy to provide a Dockerfile for a different OS than OpenSUSE but it will take some time till I find a slot for it.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">I would refrain from supporting more than a single OS. It is some effort to regularly check and update any Dockerfile. I think it is not worth it as few users will actually build the documentation on their local hosts. Users which want to build for another OS could be pointed to the possibly outdated "hints" in the README.</li>
</ul>
</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">
<p style="color: #28272d; margin: 0 0 16px;">One could of course reorganize the README and shorten it without distributing parts into other RTEMS Manuals.</p>
</li>
</ul>
</div>
</div>
<div class="footer" style="margin-top: 10px;">
<p style="font-size: small; color: #737278;">
—
<br>
<a href="https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/94#note_120511">View it on GitLab</a>.
<br>
You're receiving this email because of your account on <a target="_blank" rel="noopener noreferrer" href="https://gitlab.rtems.org">gitlab.rtems.org</a>. <a href="https://gitlab.rtems.org/-/sent_notifications/f524d38bfee68b46c457f771a4cb25d3/unsubscribe" target="_blank" rel="noopener noreferrer">Unsubscribe</a> from this thread · <a href="https://gitlab.rtems.org/-/profile/notifications" target="_blank" rel="noopener noreferrer" class="mng-notif-link">Manage all notifications</a> · <a href="https://gitlab.rtems.org/help" target="_blank" rel="noopener noreferrer" class="help-link">Help</a>
<script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","action":{"@type":"ViewAction","name":"View Issue","url":"https://gitlab.rtems.org/rtems/docs/rtems-docs/-/issues/94#note_120511"}}</script>
</p>
</div>
</body>
</html>