You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2020/01/27 13:22:14 UTC
[GitHub] [mynewt-newt] utzig opened a new pull request #368: [RFC] Add
commands to build and browse man pages
utzig opened a new pull request #368: [RFC] Add commands to build and browse man pages
URL: https://github.com/apache/mynewt-newt/pull/368
This adds a PoC level support for `newt` to generate and browse the doxygen in man-page format. No proper error handling, etc, is currently implemented...
When generating man-pages it looks for a file names `man-pages.conf ` in all repos, and if found those are run under doxygen. Generating man-pages:
```sh
$ newt man-build
Preparing man-pages, running doxygen for "apache-mynewt-nimble"
Preparing man-pages, running doxygen for "apache-mynewt-core"
Updating man-page index caches
```
Searching:
```sh
$ newt apropos os_mutex_
os_mutex_test_basic.c (3) - (unknown subject)
os_mutex_test_case_1.c (3) - (unknown subject)
os_mutex_test_case_2.c (3) - (unknown subject)
os_mutex_init (3) - (unknown subject)
os_mutex_pend (3) - (unknown subject)
os_mutex_release (3) - (unknown subject)
```
Browse a man page:
```
$ newt man os_mutex_pend
OSMutex(3) Library Functions Manual OSMutex(3)
NAME
OSMutex
SYNOPSIS
Data Structures
struct os_mutex
OS mutex structure.
Functions
os_mutex::SLIST_HEAD (, os_task) mu_head
os_error_t os_mutex_init (struct os_mutex *mu)
Create a mutex and initialize it.
os_error_t os_mutex_release (struct os_mutex *mu)
Release a mutex.
os_error_t os_mutex_pend (struct os_mutex *mu, os_time_t timeout)
Pend (wait) for a mutex.
Variables
uint8_t os_mutex::_pad
uint8_t os_mutex::mu_prio
Mutex owner's default priority.
uint16_t os_mutex::mu_level
Mutex call nesting level.
struct os_task * os_mutex::mu_owner
Task that owns the mutex.
Detailed Description
Function Documentation
...
```
The `man` commands loads the page in the given `PAGER` as would be expected...
Requires a `man-pages.conf` for each repo, eg: https://github.com/apache/mynewt-core/pull/2168
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [mynewt-newt] utzig commented on a change in pull request #368:
[RFC] Add commands to build and browse man pages
Posted by GitBox <gi...@apache.org>.
utzig commented on a change in pull request #368: [RFC] Add commands to build and browse man pages
URL: https://github.com/apache/mynewt-newt/pull/368#discussion_r374888309
##########
File path: newt/man/man.go
##########
@@ -0,0 +1,111 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package man
+
+import (
+ "fmt"
+ "path"
+
+ "mynewt.apache.org/newt/newt/project"
+ "mynewt.apache.org/newt/newt/repo"
+ "mynewt.apache.org/newt/util"
+)
+
+const MAN_DOXY_CONF = "man-pages.conf"
+const MAN_REL_PATH = "/man"
+
+func buildDoxyManPages(proj *project.Project, repo *repo.Repo) error {
+ util.StatusMessage(util.VERBOSITY_DEFAULT,
+ "Preparing man-pages, running doxygen for \"%s\"\n", repo.Name())
+
+ doxyCmd := []string{
+ "doxygen",
+ path.Join(repo.Path(), MAN_DOXY_CONF),
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ "NEWT_PROJ_ROOT": proj.BasePath,
+ "NEWT_REPO_ROOT": repo.Path(),
+ }
+
+ util.ShellCommand(doxyCmd, env)
+
+ return nil
+}
+
+func buildManDb(proj *project.Project) error {
+ util.StatusMessage(util.VERBOSITY_DEFAULT, "Updating man-page index caches")
+
+ manDbCmd := []string{
+ "mandb",
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ }
+
+ util.ShellCommand(manDbCmd, env)
+
+ return nil
+}
+
+func BuildManPages(proj *project.Project) error {
+ for _, repo := range proj.Repos() {
+ manPath := path.Join(repo.Path(), MAN_DOXY_CONF)
+ if util.NodeExist(manPath) {
+ buildDoxyManPages(proj, repo)
+ }
+ }
+ buildManDb(proj)
+
+ return nil
+}
+
+func RunMan(proj *project.Project, args []string) error {
+ manCmd := []string{
+ "/usr/bin/man",
+ args[0],
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ }
+
+ return util.ShellInteractiveCommand(manCmd, env, true)
Review comment:
> Do you see this behavior, or is it just my environment?
Thanks for testing, yes, I totally missed this! It was fixed now.
Also added proper error handling, which was missing, and updated the hard-coded `man` binary path to use `exec.LookPath` (because it runs in full screen and needs to started by `os.StartProcess` or some fork like thing!). One feature missing is pruning of existing man pages when a repo goes away, but I am not sure how to do it, maybe just `rm -rf man/`, but doesn't feel like a good thing to do...
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [mynewt-newt] ccollins476ad commented on a change in pull request
#368: [RFC] Add commands to build and browse man pages
Posted by GitBox <gi...@apache.org>.
ccollins476ad commented on a change in pull request #368: [RFC] Add commands to build and browse man pages
URL: https://github.com/apache/mynewt-newt/pull/368#discussion_r374815338
##########
File path: newt/man/man.go
##########
@@ -0,0 +1,111 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package man
+
+import (
+ "fmt"
+ "path"
+
+ "mynewt.apache.org/newt/newt/project"
+ "mynewt.apache.org/newt/newt/repo"
+ "mynewt.apache.org/newt/util"
+)
+
+const MAN_DOXY_CONF = "man-pages.conf"
+const MAN_REL_PATH = "/man"
+
+func buildDoxyManPages(proj *project.Project, repo *repo.Repo) error {
+ util.StatusMessage(util.VERBOSITY_DEFAULT,
+ "Preparing man-pages, running doxygen for \"%s\"\n", repo.Name())
+
+ doxyCmd := []string{
+ "doxygen",
+ path.Join(repo.Path(), MAN_DOXY_CONF),
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ "NEWT_PROJ_ROOT": proj.BasePath,
+ "NEWT_REPO_ROOT": repo.Path(),
+ }
+
+ util.ShellCommand(doxyCmd, env)
+
+ return nil
+}
+
+func buildManDb(proj *project.Project) error {
+ util.StatusMessage(util.VERBOSITY_DEFAULT, "Updating man-page index caches")
+
+ manDbCmd := []string{
+ "mandb",
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ }
+
+ util.ShellCommand(manDbCmd, env)
+
+ return nil
+}
+
+func BuildManPages(proj *project.Project) error {
+ for _, repo := range proj.Repos() {
+ manPath := path.Join(repo.Path(), MAN_DOXY_CONF)
+ if util.NodeExist(manPath) {
+ buildDoxyManPages(proj, repo)
+ }
+ }
+ buildManDb(proj)
+
+ return nil
+}
+
+func RunMan(proj *project.Project, args []string) error {
+ manCmd := []string{
+ "/usr/bin/man",
+ args[0],
+ }
+
+ env := map[string]string{
+ "MANPATH": path.Join(proj.BasePath, MAN_REL_PATH),
+ }
+
+ return util.ShellInteractiveCommand(manCmd, env, true)
Review comment:
When I ran `newt man-build`, the output wasn't newline-terminated:
```
[ccollins@ccollins:~/proj/myproj]$ newt man-build
Updating man-page index caches[ccollins@ccollins:~/proj/myproj]$
```
(checked out your mynewt-core man-page PR)
```
[ccollins@ccollins:~/proj/myproj]$ newt man-build
Preparing man-pages, running doxygen for "apache-mynewt-core"
Updating man-page index caches[ccollins@ccollins:~/proj/myproj]$
```
Do you see this behavior, or is it just my environment?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
[GitHub] [mynewt-newt] utzig merged pull request #368: Add commands to build
and browse man pages
Posted by GitBox <gi...@apache.org>.
utzig merged pull request #368: Add commands to build and browse man pages
URL: https://github.com/apache/mynewt-newt/pull/368
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services