Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
| doc:idealistold [2019/04/06 04:02] – Categorised page (docs) TrevorRoydhouse | doc:idealistold [2022/10/04 00:56] (current) – Chase page rename KubilayKocak | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| Here are some TODO items for The %%FreeBSD%% Documentation Project. Some of these are smaller tasks, which are relatively easy to solve and some are more complicated, | Here are some TODO items for The %%FreeBSD%% Documentation Project. Some of these are smaller tasks, which are relatively easy to solve and some are more complicated, | ||
| - | |||
| - | :!: As of 20151017, this page is in need of an update. | ||
| Note: Just because an idea is on this page it does not mean there is guarantee that there exists a consensus that the idea is a good one. | Note: Just because an idea is on this page it does not mean there is guarantee that there exists a consensus that the idea is a good one. | ||
| - | |||
| - | Long term targets: [[/ | ||
| ====== Documentation Project TODO List ====== | ====== Documentation Project TODO List ====== | ||
| Line 23: | Line 19: | ||
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| | Entity cleanups | Entities may be organized much better than we do currently. Sometimes, entities logically belonging to the same category are split into various files (trademarks.sgml and trademarks.ent) and translations do not use entity sets correctly. It seems that the general concept is not widely understood and some translations just copy English entities instead of pulling them in appropriately. This should be cleanup up and simplified in order to avoid later misuses. | Completed | GáborKövesdán | | | Entity cleanups | Entities may be organized much better than we do currently. Sometimes, entities logically belonging to the same category are split into various files (trademarks.sgml and trademarks.ent) and translations do not use entity sets correctly. It seems that the general concept is not widely understood and some translations just copy English entities instead of pulling them in appropriately. This should be cleanup up and simplified in order to avoid later misuses. | Completed | GáborKövesdán | | ||
| - | | Migrate to %%DocBook%% 4.2/XML | SGML is quite an old standard and (Open)Jade is an outdated software, whose development is discontinued. | + | | Migrate to %%DocBook%% 4.2/XML | SGML is quite an old standard and (Open)Jade is an outdated software, whose development is discontinued. |
| - | | Use XSL to generate HTML output | After XMLifying | + | | Use XSL to generate HTML output | After XML-ifying |
| - | | Evaluate xmlroff and Apache FOP for RTF, PS and PDF rendering | It would be nice if we could totally replace (Open)Jade after XMLifying | + | | Evaluate xmlroff and Apache FOP for RTF, PS and PDF rendering | It would be nice if we could totally replace (Open)Jade after XML-ifying |
| | XHTMLify webpages | Just like for our %%DocBook%% documentation, | | XHTMLify webpages | Just like for our %%DocBook%% documentation, | ||
| | Move webpages to the doc directory inside the top-level language directories | To facilitate information sharing between documentation and webpages, it would be practical to move the webpages next to the articles and books directories. | Completed | [[/ | | Move webpages to the doc directory inside the top-level language directories | To facilitate information sharing between documentation and webpages, it would be practical to move the webpages next to the articles and books directories. | Completed | [[/ | ||
| - | | Make web script multilingual | Our main Web pages are written in (American) English. The %%FreeBSD%% Translations Projects translate the web pages, Handbook and FAQ to other languages. We must translate the cgi scripts and web build scripts too. The scripts should support multiple languages, not only one. Most scripts are written in perl. Merge the perl scripts www/ | + | | Make web script multilingual | Our main Web pages are written in (American) English. The %%FreeBSD%% Translations Projects translate the web pages, Handbook and FAQ to other languages. We must translate the CGI scripts and web build scripts too. The scripts should support multiple languages, not only one. Most scripts are written in Perl. Merge the Perl scripts www/ |
| | Enhance search engine | When searching the website, the output from the search engine includes the filename that was found, which might be something like FAQ34.html. It would be more useful if the results included the question text, allowing the user to see whether or not the result was relevant. | Done (now using %%DuckDuckGo%%) | [[/ | | Enhance search engine | When searching the website, the output from the search engine includes the filename that was found, which might be something like FAQ34.html. It would be more useful if the results included the question text, allowing the user to see whether or not the result was relevant. | Done (now using %%DuckDuckGo%%) | [[/ | ||
| Line 34: | Line 30: | ||
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| - | | Dynamic web app for project ideas | Murray has started a project to move the static ideas.xml file used to keep track of summer of code and other development projects seeking volunteers into a dynamic web app that allows users to vote and post comments about the items so that it is clear which projects have the most support and so that it is easier to make updates. | + | | Dynamic web app for project ideas | Murray has started a project to move the static ideas.xml file used to keep track of summer of code and other development projects seeking volunteers into a dynamic web app that allows users to vote and post comments about the items so that it is clear which projects have the most support and so that it is easier to make updates. |
| | XMLified publications page | [[/ | | XMLified publications page | [[/ | ||
| | XML/ | | XML/ | ||
| Line 55: | Line 51: | ||
| | Write a javavmwrapper guide | The javavmwrapper tool is powerful, but probably not well-known. Describe the tool in a simple manner and make it available in an official easy to find places. This so that people know how to use the various JDKs that are installed without using aliases or modifying PATH. Same for describing where to find and how to use installed JAR files (see PR/56928). | Not started | Not assigned | | | Write a javavmwrapper guide | The javavmwrapper tool is powerful, but probably not well-known. Describe the tool in a simple manner and make it available in an official easy to find places. This so that people know how to use the various JDKs that are installed without using aliases or modifying PATH. Same for describing where to find and how to use installed JAR files (see PR/56928). | Not started | Not assigned | | ||
| | Document JDK ports | Provide up-to-date information on the status of the Java SE 5 port, the expectations regarding the Java SE 6 port. Detail the characteristics of the ports, such as stability, security and performance compared to other platforms. | Not started | Not assigned | | | Document JDK ports | Provide up-to-date information on the status of the Java SE 5 port, the expectations regarding the Java SE 6 port. Detail the characteristics of the ports, such as stability, security and performance compared to other platforms. | Not started | Not assigned | | ||
| - | | Update installation chapter | The installation chapter mostly covers %%FreeBSD%% 4.X installation. The current information is often outdated and not accurate for 5.X, 6.X and 7.X. We also have to think about installation on various platforms. This should be done under re@ team responsability | + | | Update installation chapter | The installation chapter mostly covers %%FreeBSD%% 4.X installation. The current information is often outdated and not accurate for 5.X, 6.X and 7.X. We also have to think about installation on various platforms. This should be done under re@ team responsibility |
| | Add quick and easy setup example to printing chapter | While this chapter covers in a very accurate way the configuration of a printer under %%FreeBSD%%, | | Add quick and easy setup example to printing chapter | While this chapter covers in a very accurate way the configuration of a printer under %%FreeBSD%%, | ||
| | Add info on USB printers | Nowadays printers use the USB interface, the printing chapter may need to be updated on this point. | Not started | Not assigned | | | Add info on USB printers | Nowadays printers use the USB interface, the printing chapter may need to be updated on this point. | Not started | Not assigned | | ||
| | Merge wireless article to handbook | The merge of [[http:// | | Merge wireless article to handbook | The merge of [[http:// | ||
| - | | Update | + | | Update |
| - | | Review USB audio section | One should check if we need to update the sound section for USB devices or if the current | + | | Review USB audio section | One should check if we need to update the sound section for USB devices or if the current |
| | Update emergency restore section | This section is really outdated and needs a serious " | | Update emergency restore section | This section is really outdated and needs a serious " | ||
| | Write a section on basic backup | Backing up on optical media (CD/DVD) should be presented. | Not started | Not assigned | | | Write a section on basic backup | Backing up on optical media (CD/DVD) should be presented. | Not started | Not assigned | | ||
| | Update electronic mail section | The use of Makefile facilities should be introduced for the sendmail configuration instead of the old outdated way. | Not started | %%JesusRCamou%%, | | Update electronic mail section | The use of Makefile facilities should be introduced for the sendmail configuration instead of the old outdated way. | Not started | %%JesusRCamou%%, | ||
| | Document configuring bsnmpd | The bsnmpd daemon is quite new and its configuration may be complex. The minimal common settings should be introduced in a section of the Network Servers chapter. | Not started | Not assigned | | | Document configuring bsnmpd | The bsnmpd daemon is quite new and its configuration may be complex. The minimal common settings should be introduced in a section of the Network Servers chapter. | Not started | Not assigned | | ||
| - | | Add some more tips and hints on portupgrade | There are some hints and tips on the [[/portupgrade|portupgrade]] page, which would fit better into the corresponding part of handbook | Not started | Not assigned | | + | | Add some more tips and hints on portupgrade | There are some hints and tips on the [[/ |
| | Extract relevant information from Samba mini FAQ and add them to handbook | There are some notes on [[Samba/ | | Extract relevant information from Samba mini FAQ and add them to handbook | There are some notes on [[Samba/ | ||
| | Improve indexing | Many new sections have been added to the %%FreeBSD%% Handbook without index terms, others have been added under inappropriate primary or secondary indexterms that do not fit the existing scheme. Some indexterms have been added inside list items or other areas where they are not allowed by our stylesheets, | | Improve indexing | Many new sections have been added to the %%FreeBSD%% Handbook without index terms, others have been added under inappropriate primary or secondary indexterms that do not fit the existing scheme. Some indexterms have been added inside list items or other areas where they are not allowed by our stylesheets, | ||
| - | | Update Firewall chapter | The chapter about firewalls in the handbook is becoming seriously outdated. We should also change the order in which the firewalls appear in this chapter. A better order would be: first ipfw, then pf and last ipfilter. The ipfw section should probably be rewritten and it should mention in-kernel NAT. | Not started | Not assigned | | + | | Update Firewall chapter | The chapter about firewalls in the handbook is becoming seriously outdated. We should also change the order in which the firewalls appear in this chapter. A better order would be: first IPFW, then pf and last ipfilter. The IPFW section should probably be rewritten and it should mention in-kernel NAT. | Not started | Not assigned | |
| | Check Configuration and Tuning chapter | The Configuration and Tuning chapter documents some settings which might not be relevant anymore (kern.maxfiles, | | Check Configuration and Tuning chapter | The Configuration and Tuning chapter documents some settings which might not be relevant anymore (kern.maxfiles, | ||
| | Update the Serial Communications chapter | Check if the device configuration is now version-independent (modulo node names), add an introduction | Not started | Not assigned | | | Update the Serial Communications chapter | Check if the device configuration is now version-independent (modulo node names), add an introduction | Not started | Not assigned | | ||
| | Update the Cutting-Edge Chapter for the Documentation Project CVS->SVN Conversion | ryusuke pointed out in private email that the cutting-edge chapter needs updating since c(v)sup is still mentioned for updating the documentation set. Since we do not do SVN->CVS conversion on the backend, this chapter needs updating. | | Update the Cutting-Edge Chapter for the Documentation Project CVS->SVN Conversion | ryusuke pointed out in private email that the cutting-edge chapter needs updating since c(v)sup is still mentioned for updating the documentation set. Since we do not do SVN->CVS conversion on the backend, this chapter needs updating. | ||
| - | The following list was compiled from the doc session at the [[/201010DevSummit|EuroBSDCon 2010 Devsummit]]: | + | The following list was compiled from the doc session at the [[DevSummit/201010|EuroBSDCon 2010 Devsummit]]: |
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| | Remove SLIP | SLIP is outdated and was removed from the kernel a while ago. Some PRs were sent with patches to remove SLIP from the handbook. | not started | not assigned | | | Remove SLIP | SLIP is outdated and was removed from the kernel a while ago. Some PRs were sent with patches to remove SLIP from the handbook. | not started | not assigned | | ||
| - | | Remove ISDN | ISDN has been surpassed by DSL modems and is not being used that often as it was in the past. However, the ISDN mailing list was not [[/ | + | | Remove ISDN | ISDN has been surpassed by DSL modems and is not being used that often as it was in the past. However, the ISDN mailing list was not removed, so maybe we should discuss whether we still need this section in the handbook. | not started | not assigned | |
| | Advanced/ | | Advanced/ | ||
| - | | More filesystems | There are many filesystems that are available in %%FreeBSD%% like [[/TMPFS|TMPFS]] and others. However, only ZFS is currently being described in the handbook. Add new sections about the other filesystems, | + | | More filesystems | There are many filesystems that are available in %%FreeBSD%% like [[/TMPFS]] and others. However, only ZFS is currently being described in the handbook. Add new sections about the other filesystems, |
| | Different Installation scenarios | Currently, only the standard installation via sysinstall is described. There are many other good instructions in the %%FreeBSD%% Wiki and Forums describing alternative installation methods (i.e. ZFS only, diskless). Add these in a separate section for advanced users. | not started | not assigned | | | Different Installation scenarios | Currently, only the standard installation via sysinstall is described. There are many other good instructions in the %%FreeBSD%% Wiki and Forums describing alternative installation methods (i.e. ZFS only, diskless). Add these in a separate section for advanced users. | not started | not assigned | | ||
| | Make security a top level chapter | There are many parts in the handbook that deal with security or have security related content. Security should be a top level chapter for people interested in system security. Appropriate sections need to be discussed (i.e. where to put jails: security or virtualization? | | Make security a top level chapter | There are many parts in the handbook that deal with security or have security related content. Security should be a top level chapter for people interested in system security. Appropriate sections need to be discussed (i.e. where to put jails: security or virtualization? | ||
| Line 90: | Line 86: | ||
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| - | | Add a section on Haskell ports | This task includes some general notes and the use of the hsporter utility. For the latter, there' | + | | Add a section on Haskell ports | This task includes some general notes and the use of the hsporter utility. For the latter, there' |
| | Review and separate user and developer content | Currently, porters-handbook combines some knowledge on using the Ports Collection and knowledge to develop ports. However, it is only meant to be the latter. Content that targets end-users should be moved to handbook. | Not started | Not assigned | | | Review and separate user and developer content | Currently, porters-handbook combines some knowledge on using the Ports Collection and knowledge to develop ports. However, it is only meant to be the latter. Content that targets end-users should be moved to handbook. | Not started | Not assigned | | ||
| | Move policies to a more appropriate place | Porters-handbook is for technical details of the development, | | Move policies to a more appropriate place | Porters-handbook is for technical details of the development, | ||
| | Better emphasize requirements and recommendations | We (portmgr) have to make it clear what things are Recommendations and what things are Requirements. e.g. exactly what is portmgr willing to enforce with, if necessary, backouts and commit bit suspensions. This way everyone who chafes under any "new policy" | | Better emphasize requirements and recommendations | We (portmgr) have to make it clear what things are Recommendations and what things are Requirements. e.g. exactly what is portmgr willing to enforce with, if necessary, backouts and commit bit suspensions. This way everyone who chafes under any "new policy" | ||
| - | | Reorder | + | | Reorder |
| | Document common practices | About half of the " | | Document common practices | About half of the " | ||
| | Review consistency and logical structure of sections | Some of the things in " | | Review consistency and logical structure of sections | Some of the things in " | ||
| Line 100: | Line 96: | ||
| | Fill up emacs section | The emacs section is incomplete. | Not started | [[/ | | Fill up emacs section | The emacs section is incomplete. | Not started | [[/ | ||
| | Document new *_DEPENDS style | New *_DEPENDS style with <,>,< | | Document new *_DEPENDS style | New *_DEPENDS style with <,>,< | ||
| - | | Document porting Mozilla' | + | | Document porting Mozilla' |
| | Document Portscout Variables for Port Makefiles | Port Makefiles support the use of PORTSCOUT variables to limit what Portscout will report as a new version of software. | | Document Portscout Variables for Port Makefiles | Port Makefiles support the use of PORTSCOUT variables to limit what Portscout will report as a new version of software. | ||
| ====== Developers' | ====== Developers' | ||
| - | This book needs more content. It seems a sketch rather than a consistent document. There are lots of uncovered areas but there are some sporadic pieces of information on the wiki, which could be SGMLified | + | This book needs more content. It seems a sketch rather than a consistent document. There are lots of uncovered areas but there are some sporadic pieces of information on the wiki, which could be SGML-ified |
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| - | | Merge description on Linux cross-development | There is a short description on how to use %%FreeBSD%% for cross-developing Linux binaries on [[/ | + | | Merge description on Linux cross-development | There is a short description on how to use %%FreeBSD%% for cross-developing Linux binaries on [[/ |
| | Add content on general debugging | Some information may be extracted from [[/ | | Add content on general debugging | Some information may be extracted from [[/ | ||
| | Add content on using profiling to detect performance bottlenecks | Profiling with gprof is very useful to detect performance bottlenecks but it is not widely utilized. | Not started | Not assigned | | | Add content on using profiling to detect performance bottlenecks | Profiling with gprof is very useful to detect performance bottlenecks but it is not widely utilized. | Not started | Not assigned | | ||
| - | | Add content on dealing with TTYs | Some information of the redesigned TTY subsistem | + | | Add content on dealing with TTYs | Some information of the redesigned TTY subsystem |
| ====== Marketing articles ====== | ====== Marketing articles ====== | ||
| - | The Marketing Team (marketing@%%FreeBSD%%.org) | + | The Marketing Team is working on creating a series of whitepapers to explain the advantages of %%FreeBSD%% to a general technical audience. |
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| - | | %%FreeBSD%% for Solaris users | Write a short article on %%FreeBSD%% for Solaris users. We have support for DTrace and ZFS. Jails can be a good alternative for zones, so it seems we have a good migration path but we need to document it better. | Not started | Not assigned | | + | | %%FreeBSD%% for Solaris users | Write a short article on %%FreeBSD%% for Solaris users. We have support for [[/DTrace]] and [[/ZFS]]. Jails can be a good alternative for zones, so it seems we have a good migration path but we need to document it better. | Not started | Not assigned | |
| | Clustering with %%FreeBSD%% | Write an article on how to plan a clustered system with %%FreeBSD%%. | Not started | Not assigned | | | Clustering with %%FreeBSD%% | Write an article on how to plan a clustered system with %%FreeBSD%%. | Not started | Not assigned | | ||
| | %%FreeBSD%% for hosting providers | Write an article on how to use %%FreeBSD%% for common hosting tasks (jails, performance, | | %%FreeBSD%% for hosting providers | Write an article on how to use %%FreeBSD%% for common hosting tasks (jails, performance, | ||
| Line 127: | Line 123: | ||
| ^ Task ^ Description ^ Status ^ Responsible ^ | ^ Task ^ Description ^ Status ^ Responsible ^ | ||
| - | | Create a source code management book | We use CVS and SVN for mainline development but we also have a Perforce repository and a user area in SVN for experimental development branches. Also, some developers use Mercurial or git for local development. We should collect all information related to the topic to a new book and arrange it in a logical and consistent way. This task would involve SGMLifying the < | + | | Create a source code management book | We use CVS and SVN for mainline development but we also have a Perforce repository and a user area in SVN for experimental development branches. Also, some developers use Mercurial or git for local development. We should collect all information related to the topic to a new book and arrange it in a logical and consistent way. This task would involve SGMLifying the < |
| | Write missing manpages | There is a list of missing manpages on [[/ | | Write missing manpages | There is a list of missing manpages on [[/ | ||
| | Add some information on power consumption tuning into the laptop article | [[/ | | Add some information on power consumption tuning into the laptop article | [[/ | ||
| Line 144: | Line 140: | ||
| ---- | ---- | ||
| - | {{tag> | + | {{tag> |